PHPDoc

1. PHPDoc By: Ana Marie Chanaba & Joseph Casabona

2. Overview • Introduction: What is PHPDoc • The Installation Process • Online Resources • Initializing PHPDoc • Hard Coding • Web Interface

3. Overview- cont. • Documenting the Code • DocBlock Templates • Observations • Conclusion

4. What is PHPDoc? • PHPDoc is an adaptation of JavaDoc for PHP. It is a widely easy-to-use documentation generator for PHP code • Uses PHP Objects to generate documentation • PHPDocumentor • DocBlocks

5. Installing PHPDoc • Download PHPDoc • http://www.phpdoc.de/ • Sourceforge.net http://sourceforge.net/project/showfiles.php?group_id=11194

6. Installing the Web Interface • To use the web interface, you must have a web server such as Apache installed, and must have a working PHP for that web server.

7. Apache Server If developers want to use PHPDoc's web interface, they simply have to unzip the archive and put it into the directory that is appended onto the user’s home directory. UserDir "My Documents/unix_web"

8. Installation • The default for extracting PHPDoc is “C:\My Documents\unix_web\phpdoc”. • You should now be able to get to the PHPDoc interface by querying http://localhost/~username/phpdoc/PphDocumentor.

9. Web Interface

10. File tab Web Interface

11. Output Tab Web Interface

12. Documentation

13. Documentation

14. Initializing PHPDoc • Hard Code Initialization • Initialize PHPDoc Objects define("PHPDOC_INCLUDE_DIR", "C:/Program Files/Apache Software Foundation/Apache2.2/htdocs/PHPDoc/"); define("LINEBREAK", "\r\n"); include("PHPDoc/prepend.php"); $doc = new Phpdoc; $doc->setApplication("Joe's Resume"); $doc->setSourceDirectory(PHPDOC_INCLUDE_DIR); $doc->setTarget(PHPDOC_INCLUDE_DIR."apidoc/resume/"); $doc->setTemplateDirectory(PHPDOC_INCLUDE_DIR."renderer/html/templates/"); $doc->setSourceFileSuffix( array ("php", "inc") );

15. Initializing PHPDoc • Hard Coding- cont. • Two lines to render documentation $doc->parse(); $doc->render();

16. Documenting the Code • All source code should contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class. • /** begins a DocBlock • **/ ends a DocBlock

17. Documenting the Code • * must be at the beginning of a line within a DocBlock • @ is a special way to start the DocBlock Line

18. Documenting the Code • Sample Function: /** * A sample function docblock * @global string document the fact that this function uses $_myvar * @staticvar integer $staticvar this is actually what is returned * @param string $param1 name to declare * @param string $param2 value of the name * @return integer */ function firstFunc($param1, $param2 = 'optional') { static $staticvar = 7; global $_myvar; return $staticvar; }

19. DocBlock Templates • PHPDoc allows developers to reduce unneeded typing by using DocBlock templates

20. Before DocBlock Template class Bob {      // beginning of docblock template area          /**#@+      * @access private       * @var string       */      var $_var1 = 'hello';      var $_var2 = 'my';          /**       * Two words       */      var $_var8 = 'like strings';      /**#@-*/      var $publicvar = 'Lookee me!'; }

21. After DocBlock Template class Bob {     // beginning of docblock template area           /**       * @access private       * @var string        */      var $_var1 = 'hello';      /**       * @access private       * @var string        */      var $_var2 = 'my';      /**        * @access private       * @var string        */ /**    * Two words     */      var $_var8 = 'like strings';      var $publicvar = 'Lookee me!'; }

22. Observations • PHPDoc great for documenting functions and classes • Makes page run slower • A lot of overhead • PHPDoc documentation generated each time

23. Conclusion • Documentation needed in coding • PHPDoc is easy to use, fairly straight forward • Generates extensive code based on comments