Php Docs


Published on

Small presentation on PHP Docs

Published in: Technology, Design
1 Like
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Php Docs

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