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
● 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
Top Related