The most hated thing a developer can imagine is writing documentation but on the other hand nothing can compare with a well documented source code if you want to change or extend some code. PhpDocumentor is one of many tools enabling you to parse the inline documentation and generate well structured and referenced documents. This tallk will show you how to get the most out of phpDocumentor and shall enable you to write fantastic documentation.

1. The Beauty and the Beast
Bastian Feder OSIDays 2010
Liip Inc. 20.09.2010

2. Me, myself and I
● Senior application developer & architect
● Prof. trainer
● PHP since 2001
● JavaScript since 2002
● Liip Inc. since 2010

3. Who are you?

4. Agenda
● What is this phpDocumentor everyone is talking
about?
● Doh! Too less space for a complete
documentation!
● Nice so far! Are there tools supporting this
thing?
● Where to find more information.

5. What is this phpDocumentor?
● Command line tool
● Written in PHP
● Identifies annotations (tags)
● Converters render different formats (HTML,
Smarty, DocBook, etc)
● Automated documentation

6. Drawbacks
● Memory consuming
set memory_limit up
● Time consuming
set max_execution_time

7. 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.

8. DocBlock – example
<?php
/**
* Just a DocBlock example
*
* this is an example for a phpDocumentor class documentation block
*
* @package myProject
* @subpackage examples
*
* @revision pre-alpha 1
*/
class foo {
/**
* Just returns a boolean.
*
* @retrun boolean Just true.
*/
public function bar() {
return true;
}
}

9. Tag annotation - examples
● @package, @subpackage, @category
● @author, @license, @version
● @param, @return
● @access
● @see, @link, @uses
● @todo
● @example, @tutorial

10. 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 "{@link" in a docblock, I just use "{@}link." If
* I want the characters "{@*}" I use "{@}*}"
*/
function bar() {
return;
}

11. Page 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.
*
* @package papayaCMS
* @version $Id: index.php 19965 2008-08-11 12:23:29Z feder $
*/

12. 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}

13. Tutorials
● Ability to link in external documentation
● DocBook format
● Hooks are the inline{} tags
● Enable rendering the tutorial:
– Existing subdir named „tutorials“
– Comandline switch „-d“, „--directory“, „-f“ or „--
filename“ must contain the subdir
– Predefined structure:
tutorials/package/package.pkg

14. Tutorials – example integration
/**
* FluentDOM implements a jQuery like replacement for DOMNodeList
*
* @version $Id: FluentDOM.php 338 2009-09-28 13:21:22Z lapis $
* @license http://www.opensource.org/licenses/mit-license.php The MIT License
* @copyright Copyright (c) 2009 Bastian Feder, Thomas Weinert
*
* @tutorial FluentDOM.pkg
* @package FluentDOM
*/

15. Tutorials - example
FluentDOM.pkg
<refentry id="{@id}">
<refnamediv>
<refname>User Guide for FluentDOM</refname>
<refpurpose></refpurpose>
</refnamediv>
<refsynopsisdiv>
<author>Bastian Feder</author>
<author>Thomas Weinert</author>
</refsynopsisdiv>
{@toc}
<refsect1 id="{@id intro}">
<title>FluentDOM</title>
<para>
FluentDOM ist a jQuery like fluent XML interface for the DOMDocument in PHP.
</para>
<para>
The idea was born in a workshop of {@link http://schlitt.info Tobias Schlitt},
about the PHP XML extensions at the IPC Spring, in Berlin. He used this idea to show
XPath samples in the session.
</para>
</refsect1>
</refentry>

16. Rendered tutorial example
See http://fluentdom.github.com/docs/index.html for the complete version.

17. Quality check
● Error log
(errors.html in root of API documentation)
● Todo list
(todolist.html in root of API documentation)

18. 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 $

19. SVN / CVS identifier (II)
● Location of 'config' – file:
– MacOsX/Linux:
~/.subversion/config
– WinXp:
C:Dokumente und Einstellungen
<USER>AnwendungsdatenSubversion
config

20. 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=Id URL
*.htm = svn:eol-style=LF;svn:mime-type=text/html;svn:keywords=Id 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

21. 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;

22. Eclipse PDT – docu hints (II)
● 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.

23. Eclipse PDT – docu hints (III)
● Magic methods ● Magic properties
– __clone() – __set()
– __empty() – __get()
– ...
/**
* FluentDOM implements a jQuery like replacement for DOMNodeList
*
* @property string $contentType Ouput type – text/xml or text/html
* @property-read DOMDocument $document An instance of the current DOMDocument
* @property-read DOMXPath $xpath An Instance of the current DOMXPath object
*
* @method bool empty() clears the current node list identified by a selector
* @method DOMDocument clone() clones the current node list identified by a selector
*
* @package FluentDOM
*/

24. Eclipse PDT – docu hints

25. external Tools framework
● Enables Eclipse to run ‚stand-alone‘
applications
● Two broad classes of external tools are
available:
– Ant build files
– Everything else

26. How to integrate

27. 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.

28. How to integrate (III)
● Display in favorites
menu
● Standard Input and
Output

29. Any questions left?

30. Slides'n Feedback
● Sildes
(http://www.slideshare.net/lapistano)
● Feedback
– Personal contact
(lapistano@php.net)
– Joind'in
(http://joind.in/event/view/425 )

31. References
● phpDocumentor website @ pear.php.net
(http://pear.php.net/package/PhpDocumentor/docs/1.4.4)
● phpDocumentor Manual
(http://manual.phpdoc.org)
● FluentDOM
(http://fluentdom.org)
● Eclipse website
(http://eclipse-org/pdt)
● SVN keyword substitution
(http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.advanced.props.special.keywords)

32. 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