![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){ …}}](https://image.slidesharecdn.com/phpdoc-091113044504-phpapp01/85/PHPDoc-9-320.jpg)
PHPDoc
- 2. Formalstandard of PHP-codecommentingBasedonJavadocImprovedreadability of code commentsAuto-generatedocumentationCanbeinterpretedbyIDE’sEclipse, Zend Studio, Aptana, NetBeans..?phpDoc(umentor) ?
- 3. DocBlocksStarts with/**Eachnewline starts with*Endswith*/on a newline/** * This is a DocBlock */Precedes the element thatwillbedocumented
- 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 descriptionsFirst line, endswith blank line (* ) orperiodMax 3 lines longLong descriptionsNo length limitCan have multiple paragraphsCan have HTML styletagsDocBlocks/** * 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
- 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 fileOnlyDocBlocknot to precedean elementFirst in a fileMust have a @packageNextdefine, class, function must have itsownDocBlockPage 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 packagePage- and class-levelvariantsClass and Page-leveldocBlocksalways have @packageIfnotsuppliedparserclass) willuseDefaultorinheritfromparent (extendedclass)Packages/*** Zend_Form_Element_Button* @packageZend_Form*@subpackageElement*/
- 13. GeneratedocumentationphpDocumentorDoxygenCommandline & PHP appJust PHP filesManytemplatesSmartyextensionDocbook outputTextual link diagramsHighlighting and linkingSlowerLesseroptionshttp://docs.magentocommerce.com/Commandline & GUIManyformats, C++, C#, PHP, Java…OnetemplateXSLT extensionNo Docbook outputVisual link diagramsNo highlightorlinkingFasterMore optionshttp://svn.wikimedia.org/doc/