PHP Starter Day 2008
PHPDocumentor
The Beauty and the Beast
Bastian Feder
papaya Software GmbH
27.10.2008

Me, myself & I
 application developer
 PHP seit 2001
 papaya CMS seit
01.2008

Agenda
 phpDocumentor tags
 The DocBlock
 SVN
 Additional features
 Eclipse PDT
▹ Documentation hints
▹ Integrate phpDocumentor
 References

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.

phpDocumentor tags (examples)
 @package, @subpackage, @category
 @author, @license, @version
 @param, @return
 @access
 @see, @link, @uses
 @todo

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 $
*/

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}

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

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

Quality check
 error log
(errors.html in root of API documentation)
 todo list
(todolist.html in root of API documentation)

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 $

SVN / CVS identifier (II)
 Location of 'config' – file:
▹ MacOsX/Linux:
~/.subversion/config
▹ WinXp:
C:\\Dokumente und Einstellungen\\
<USER>\\Anwendungsdaten\\Subversion\\config

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

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;

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.

Eclipse PDT – docu hints

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

How to integrate

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.

How to integrate (III)
 Display in favorites
menu
 Standard Input and
Output

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)

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