1. phpDoc GFM (06-11-09) PieterjanFiers

2. Formalstandard of PHP-codecommenting BasedonJavadoc Improvedreadability of code comments Auto-generatedocumentation CanbeinterpretedbyIDE’s Eclipse, Zend Studio, Aptana, NetBeans..? phpDoc(umentor) ?

4. define() statements, functions, classes, class methods, and class vars, include() statements, and global variables/** * DocBlock for function foo? * * No, this will be for the constant me! */ define('me',2); function foo($param = me) { }

5. Short descriptions First line, endswith blank line (* ) orperiod Max 3 lines long Long descriptions No length limit Can have multiple paragraphs Can have HTML styletags DocBlocks /** * Short description. * * Long description first sentence starts here * and continues on this line for a while * finally concluding here at the end of * this paragraph * * <p>The blank line above denotes a paragraph * break</p> * <p>Or P-tags</p> */

6. DocBlockmarkup-tags <b> emphasize/bold text <code>  Use this to surround php code, some converters will highlight it <br>  hard line break, may be ignored by some converters <i>  italicize/mark as important <kbd>  denote keyboard input/screen display <li>  list item <ol>  ordered list <p>  If used to enclose all paragraphs, otherwise it will be considered text <pre>  Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA) <samp>  denote sample or examples (non-php) <ul>  unordered list <var>  denote a variable name

7. phpDocTags

8. phpDocTags http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html

9. DocBlocks /** * Short classdescription. * * @package[classPackage]*/ ClassmyClass() { /** * property description * * @var [vartype] */ $myvar = 0; /** * Methoddescription * * @param [vartype] $[long_varname] param-description * @param [long_vartype] $[varname] param-description * * @return [vartype] */ Public functiondoStuff($longvarname, $varname) { … } }

10. Document content of a file OnlyDocBlocknot to precedean element First in a file Must have a @package Nextdefine, class, function must have itsownDocBlock Page level docBlocks <?php /** * Page-level DocBlock * @package pagepackage */ /** * Define DocBlock */ define(“FOO",“Bar");

11. A set of data, files, classes, functions,… Canbeviewed as one ‘product’ SubPackagesrequire a package Page- and class-levelvariants Class and Page-leveldocBlocksalways have @package Ifnotsuppliedparserclass) willuseDefaultorinheritfromparent (extendedclass) Packages /** * Zend_Form_Element_Button * @packageZend_Form *@subpackageElement */

12. Reducerepetition Start with/**#@+ End #@-*/ Templates /**#@+ * @access private * @var string */ var $_var1 = 'hello'; var $_var2 = 'my'; var $_var3 = 'name'; var $_var4 = 'is'; /** * Two words */ var $_var5 = 'like strings'; /**#@-*/

13. Generatedocumentation phpDocumentor Doxygen Commandline & PHP app Just PHP files Manytemplates Smartyextension Docbook output Textual link diagrams Highlighting and linking Slower Lesseroptions http://docs.magentocommerce.com/ Commandline & GUI Manyformats, C++, C#, PHP, Java… Onetemplate XSLT extension No Docbook output Visual link diagrams No highlightorlinking Faster More options http://svn.wikimedia.org/doc/