Php Documentor The Beauty And The Beast

6,271 views

Published on

This presentation givs a short overview about phpDocumentor and shows how to use it inside Eclipse PDT

Published in: Technology

Php Documentor The Beauty And The Beast

  1. 1. PHP Starter Day 2008 PHPDocumentor The Beauty and the Beast Bastian Feder papaya Software GmbH 27.10.2008
  2. 2. Me, myself & I  application developer  PHP seit 2001  papaya CMS seit 01.2008
  3. 3. Agenda  phpDocumentor tags  The DocBlock  SVN  Additional features  Eclipse PDT ▹ Documentation hints ▹ Integrate phpDocumentor  References
  4. 4. phpDocumentor tags  a phpDocumentor tag is an annotation telling a parser what to do with the given information.  rendering template decides which information will be displayed.
  5. 5. phpDocumentor tags (examples)  @package, @subpackage, @category  @author, @license, @version  @param, @return  @access  @see, @link, @uses  @todo
  6. 6. DocBlock definition /** * This is an example short description of a phpDocumentor DocBlock. * * This example shall show how a DocBlock shall look like and what information are * to be displayed. * This text and the upper license will be displayed in the rendered documentation as the * so called long description of the DocBlock. * * @copyright 2002-2008 by papaya Software GmbH - All rights reserved. * @link http://www.papaya-cms.com/ * @license GNU General Public Licence (GPL) 2 http://www.gnu.org/copyleft/gpl.html * * You can redistribute and/or modify this script under the terms of the GNU General Public * License (GPL) version 2, provided that the copyright and license notes, including these * lines, remain unmodified. papaya is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. * * @author Thomas Weinert <info@papaya-cms.com> * @package papaya * @version $Id: index.php 19965 2008-08-11 12:23:29Z rekowski $ */
  7. 7. DocBlock inheritence  @author, @version, and @copyright are automatically inherited unless explicitly specified in the DocBlock  @package and @subpackage are inherited unless explicitly specified in the DocBlock  If there is no short description, the short description will be inherited.  If there is no long description, the long description will be inherited.  If there is a long description, and you still want to inherit the parent's description, use inline {@inheritdoc}
  8. 8. Additional features (inline{} tags)  display their information in the text flow /** * inline tags demonstration * * this function works heavily with {@link foo()} to rule the world. If I want * to use the characters quot;{@linkquot; in a docblock, I just use quot;{@}link.quot; If * I want the characters quot;{@*}quot; I use quot;{@}*}quot; */ function bar() { return; }
  9. 9. Additional features (tutorials)  ability to link in external documentation  hooks are the inline{} tags  enable rendering the tutorial: ▹ existing subdir named „tutorials“ ▹ comandline switch „-d“, „--directory“, „-f“ or „-- filename“ must contain the subdir
  10. 10. Quality check  error log (errors.html in root of API documentation)  todo list (todolist.html in root of API documentation)
  11. 11. SVN / CVS identifier  $Date: $ ▹ $Date: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $  $Revision: $ ▹ $Revision: 144 $  $Author: $ ▹ $Author: feder $  $headURL: $ ▹ $HeadURL: http://svn.papaya.local/svn/weisseliste/trunk/README $  $Id: $ ▹ $Id: content_assistant_step.php 19696 2008-08-05 15:52:41Z feder $
  12. 12. SVN / CVS identifier (II)  Location of 'config' – file: ▹ MacOsX/Linux: ~/.subversion/config ▹ WinXp: C:Dokumente und Einstellungen <USER>AnwendungsdatenSubversionconfig
  13. 13. SVN / CVS identifier (III)  add following lines to configuration file: [miscellany] global-ignores = *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store .project .cache .settings enable-auto-props = yes [auto-props] *.js = svn:eol-style=LF;svn:keywords=Id LastChangedDate LastChangedRevision URL *.css = svn:eol-style=LF;svn:keywords=Id LastChangedDate LastChangedRevision URL *.php = svn:eol-style=LF;svn:keywords=Id LastChangedDate LastChangedRevision URL *.html = svn:eol-style=LF;svn:mime-type=text/html;svn:keywords=LastChangedDate LastChangedRevision URL *.htm = svn:eol-style=LF;svn:mime-type=text/html;svn:keywords=LastChangedDate LastChangedRevision URL *.xsl = svn:eol-style=LF *.xml = svn:eol-style=LF *.xsd = svn:eol-style=LF *.sql = svn:eol-style=LF *.txt = svn:eol-style=LF
  14. 14. Eclipse PDT – docu hints if you plan to instantiate a new object in your class, declare the name of the class to be instantitated as type of the class var you will use. /** * Example description for a public class var. * * @var base_plugin */ protected $basePluginObj;
  15. 15. Eclipse PDT – docu hints  once you declared the complete function DocBlock, Eclipse is able to show you these information in the tooltip of the function call.  try to hit F2 when the tooltip appears. This will set the focus to the tooltip and it can be resized to see the complete info.
  16. 16. Eclipse PDT – docu hints
  17. 17. external Tools framework  Enables Eclipse to run ‚stand-alone‘ applications  Two broad classes of external tools are available: ▹ Ant build files ▹ Everything else
  18. 18. How to integrate
  19. 19. How to integrate (II)  Location points to the phpDocumentor installation  Working Directory directory to store temporary data  Arguments command line parameters to be passed to phpDocumentor '-c' defines the location of a configuration file '${project_loc}' Eclipse variable representing the location of the current selected project.
  20. 20. How to integrate (III)  Display in favorites menu  Standard Input and Output
  21. 21. References  phpDocumentor website @ pear.php.net (http://pear.php.net/package/PhpDocumentor/docs/1.4.2)  SVN keyword substitution (http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.advanced.props.special.keywords)
  22. 22. License  This set of slides and the source code included in the download package is licensed under the Creative Commons Attribution- Noncommercial-Share Alike 2.0 Generic License  http://creativecommons.org/licenses/by-nc-sa/2.0/deed.en

×