Php Docs

Php Docs

• 1.
  PHPDocs @author PabloVíquez < [email_address] >
• 2.
  Agenda Explanation ofthe require and most used tags Tips & Tricks Example
• 3.
  @package Specify packageto group classes or functions and defines into. Usage: @package Navigation Generates a warning if not included 2 types: page-level package (defines, functions, includes/requires) class-level package (class, all its variables and methods)
• 4.
  @subpackage Specify sub-packageto group classes or functions and defines into Usage @ subpackage Ca_Navigation IF @package is not found, @subpackage is ignored
• 5.
  @var Document thedata type of a class variable Usage @var <data_type> Must be a valid PHP datatype: bool, string, int, mixed , array… Use for class data members
• 6.
  @author Author ofthe current element Can be use on anything Will try to parse the text inside <> as email Usage @author Pablo Viquez <pviquez@schematic.com>
• 7.
  @todo Document changesthat will be made in the future Usage @todo One line explaining the todo
• 8.
  @ version Version of the current document OSPG standard usage: @version $Id$ SVN on command line svn propset svn:keywords Id filename SVN config file: (~/.subversion/config) enable-auto-props = yes [auto-props] *.php = svn:keywords=Id *.* = svn:keywords=Id
• 9.
  @see Display alink to the documentation for an element Usage: @see Navigation Display links ONLY for elements on the documentation, its not for links or external references The parser can be told where to look :: -Which class to look in for the element. ie classname::$variablename. () -When present at the end of elementname, like elementname(), this tells the @see parser to search for a function or method. $ -When present at the beginning of elementname, like $elementname, this tells the @see parser to search for a variable in the current class.
• 10.
  @link Display ahyperlink to a URL in the documentation Usage @link http://www.schematic.com Might be use on any element
• 11.
  @abstract Document anabstract class, class variable or method Use the @abstract tag to declare a method, class variable, or class that must be re-defined in a child class to be valid. The @abstract tag is only valid in PHP 4 , PHP 5 has a keyword abstract.
• 12.
  @access Access controlfor an element. Usage @access private|public @access private prevents documentation of the element unless specified by command-line It’s not require on PHP5 classes, since functions does have the keyword
• 13.
  @final Document aclass method that should never be overridden in a child class. Usage: @final [description] The @final tag is only valid in PHP 4 , PHP 5 has a keyword final.
• 14.
  @example (1/2) Includean external example file with syntax highlighting Usage: @example <full_file_path_path |relative_file_path > Used to parse an example file for syntax highlighting and linking to documentation
• 15.
  Inline @example Reallycool when you don’t want to include a file just display how to use it Usage: /** * This function was created to show a PHP docs example * * You can also do usage examples as follow: * <code> * $ca_Navigation = Ca_Navigation(); * echo $ca_Navigation->aSimpleFunction(1,'Pablo'); * </code> * */
• 16.
  Tips & TricksWhen generating the PHPDocs, always look for errors.html You can use some HTML elements in the documentation: <p>, <b>, <li>, <ol>, <ul>, <code>, <pre> IF for any reason you need to display <b> in the documentation, use double delimiter <<b>> If you need to close a comment inside of the <code> tag use {@*}