The Beauty and the Beast

Bastian Federpapaya Software GmbH

PHPBCAT201001.05.2010

Me, myself and I

application developer PHP since 2001 JavaScript since 2002 papaya CMS seit 01.2008

Who are you?

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.

What is this phpDocumentor?

● Automated documentation● Identifies annotations (tags)● Command line tool● Written in PHP● Converters render different formats (HTML,

Smarty, DocBook, etc)

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.

Tags - examples

● @package, @subpackage, @category● @author, @license, @version● @param, @return● @access● @see, @link, @uses● @todo● @example, @tutorial

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; }

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 Papaya-Modules* @subpackage Free-Domains* @version $Id: connector_domains.php 19965 2010-04-11 12:23:29Z feder $*/

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}

Commandline options

$> phpdoc -h

-d --directory name of a directory(s) to parse directory1,directory2 -t --target path where to save the generated files -ti --title title of generated documentation, default is 'Generated Documentation' -pp --parseprivate parse @internal and elements marked private with @access. Use on/off, default off -o --output output information to use separated by ','. Format: output:converter:templatedir like "HTML:frames:phpedit" -c --useconfig Use a Config file in the users/ subdirectory for all command-line options

...

User conifguration file

● Templates in subdir 'user'● Covers complete configuration options● Additional description each option

$> phpdoc -c PATH/TO/myConf.ini

Generated documentation

Tutorials

● DocBook format● Link in external documentation (inline{})● 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– tutorials/package/subpackage/subpackage.pkg

Tutorials – types

● Package tutorials● File extension: .pkg

● Class tutorials● File extension: .cls

● Procedural code tutorials● File extension: .proc

Tutorials – example annotation

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

Tutorials – example

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

FluentDOM.pkg

Tutorials – generated output

Quality check

● Error log (errors.html in root of API documentation)

● Todo list (todolist.html in root of API documentation)

SVN identifiers

● $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 .settingsenable-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

Eclipse PDT – docu hints

/*** Example description for a public class var.** @var base_plugin*/protected $basePluginObj;

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.

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.

Eclipse PDT – docu hints (III)

● Magic methods● __clone()● __empty()● ...

● Magic properties● __set()● __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*/

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)

● Locationpoints to the phpDocumentor installation

● Working Directorydirectory to store temporary data

● Argumentscommand 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

Any questions left?

Slides'n Feedback

● Sildes(http://www.slideshare.net/lapistano)

● Feedback ● Personal contact

(conference@bastian-feder.de)

● Joind'in(http://joind.in/user/view/557)

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)

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