phpDoc<br />GFM (06-11-09)<br />PieterjanFiers<br />
Formalstandard of PHP-codecommenting<br />BasedonJavadoc<br />Improvedreadability of code comments<br />Auto-generatedocum...
DocBlocks<br />Starts with/**<br />Eachnewline starts with*<br />Endswith*/on a newline<br />/**<br /> * This is a DocBloc...
define() statements, functions, classes, class methods, and class vars, include() statements, and global variables</li></u...
Short descriptions<br />First line, endswith blank line (* ) orperiod<br />Max 3 lines long<br />Long descriptions<br />No...
DocBlockmarkup-tags<br />&lt;b&gt; emphasize/bold text<br />&lt;code&gt;  Use this to surround php code, some 			    con...
phpDocTags<br />
phpDocTags<br />http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html<br />
DocBlocks<br />/**<br /> * Short classdescription.<br /> * <br /> * @package[classPackage]*/<br />ClassmyClass()<br />{<br...
Document content of a file<br />OnlyDocBlocknot to precedean element<br />First in a file<br />Must have a @package<br />N...
A set of data, files, classes, functions,…<br />Canbeviewed as one ‘product’<br />SubPackagesrequire a package<br />Page- ...
Reducerepetition<br />Start with/**#@+<br />End #@-*/<br />Templates<br />/**#@+<br />  * @access private<br />  * @var st...
Upcoming SlideShare
Loading in …5
×

PHPDoc

1,507 views

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,507
On SlideShare
0
From Embeds
0
Number of Embeds
12
Actions
Shares
0
Downloads
26
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

PHPDoc

  1. 1. phpDoc<br />GFM (06-11-09)<br />PieterjanFiers<br />
  2. 2. Formalstandard of PHP-codecommenting<br />BasedonJavadoc<br />Improvedreadability of code comments<br />Auto-generatedocumentation<br />CanbeinterpretedbyIDE’s<br />Eclipse, Zend Studio, Aptana, NetBeans..?<br />phpDoc(umentor) ?<br />
  3. 3. DocBlocks<br />Starts with/**<br />Eachnewline starts with*<br />Endswith*/on a newline<br />/**<br /> * This is a DocBlock */<br /><ul><li>Precedes the element thatwillbedocumented
  4. 4. define() statements, functions, classes, class methods, and class vars, include() statements, and global variables</li></ul>/** <br /> * DocBlock for function foo? <br /> * <br /> * No, this will be for the constant me! <br /> */<br />define(&apos;me&apos;,2); <br />function foo($param = me) {<br />}<br />
  5. 5. Short descriptions<br />First line, endswith blank line (* ) orperiod<br />Max 3 lines long<br />Long descriptions<br />No length limit<br />Can have multiple paragraphs<br />Can have HTML styletags<br />DocBlocks<br />/**<br /> * Short description.<br /> * <br />* Long description first sentence starts here <br />* and continues on this line for a while<br />* finally concluding here at the end of<br />* this paragraph<br /> *<br />* &lt;p&gt;The blank line above denotes a paragraph<br />* break&lt;/p&gt; <br />* &lt;p&gt;Or P-tags&lt;/p&gt; */<br />
  6. 6. DocBlockmarkup-tags<br />&lt;b&gt; emphasize/bold text<br />&lt;code&gt;  Use this to surround php code, some converters will highlight it<br />&lt;br&gt;  hard line break, may be ignored by some converters<br />&lt;i&gt;  italicize/mark as important<br />&lt;kbd&gt;  denote keyboard input/screen display<br />&lt;li&gt;  list item<br />&lt;ol&gt;  ordered list<br />&lt;p&gt;  If used to enclose all paragraphs, otherwise it will be considered text<br />&lt;pre&gt;  Preserve line breaks and spacing, and assume all tags are text (like XML&apos;s CDATA)<br />&lt;samp&gt;  denote sample or examples (non-php)<br />&lt;ul&gt;  unordered list<br />&lt;var&gt;  denote a variable name<br />
  7. 7. phpDocTags<br />
  8. 8. phpDocTags<br />http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html<br />
  9. 9. DocBlocks<br />/**<br /> * Short classdescription.<br /> * <br /> * @package[classPackage]*/<br />ClassmyClass()<br />{<br />/**<br />* property description<br /> * <br /> * @var [vartype]<br />*/<br />$myvar = 0;<br />/**<br /> * Methoddescription<br /> * <br /> * @param [vartype] $[long_varname] param-description<br /> * @param [long_vartype] $[varname] param-description<br /> * <br /> * @return [vartype]<br />*/ <br />Public functiondoStuff($longvarname, $varname)<br />{<br /> …<br />}<br />}<br />
  10. 10. Document content of a file<br />OnlyDocBlocknot to precedean element<br />First in a file<br />Must have a @package<br />Nextdefine, class, function must have itsownDocBlock<br />Page level docBlocks<br />&lt;?php<br />/**<br /> * Page-level DocBlock<br /> * @package pagepackage<br /> */<br />/**<br /> * Define DocBlock<br /> */<br />define(“FOO&quot;,“Bar&quot;);<br />
  11. 11. A set of data, files, classes, functions,…<br />Canbeviewed as one ‘product’<br />SubPackagesrequire a package<br />Page- and class-levelvariants<br />Class and Page-leveldocBlocksalways have @package<br />Ifnotsuppliedparserclass) willuseDefaultorinheritfromparent (extendedclass)<br />Packages<br />/**<br />* Zend_Form_Element_Button<br />* @packageZend_Form<br />*@subpackageElement<br />*/<br />
  12. 12. Reducerepetition<br />Start with/**#@+<br />End #@-*/<br />Templates<br />/**#@+<br />  * @access private<br />  * @var string<br />  */<br />var $_var1 = &apos;hello&apos;;<br />var $_var2 = &apos;my&apos;;<br />var $_var3 = &apos;name&apos;;<br />var $_var4 = &apos;is&apos;;<br />/**<br /> * Two words<br />  */<br />var $_var5 = &apos;like strings&apos;;<br />/**#@-*/<br />
  13. 13. Generatedocumentation<br />phpDocumentor<br />Doxygen<br />Commandline & PHP app<br />Just PHP files<br />Manytemplates<br />Smartyextension<br />Docbook output<br />Textual link diagrams<br />Highlighting and linking<br />Slower<br />Lesseroptions<br />http://docs.magentocommerce.com/<br />Commandline & GUI<br />Manyformats, C++, C#, PHP, Java…<br />Onetemplate<br />XSLT extension<br />No Docbook output<br />Visual link diagrams<br />No highlightorlinking<br />Faster<br />More options<br />http://svn.wikimedia.org/doc/<br />

×