The beautyandthebeast phpbat2010

The Beauty and the Beast Bastian Feder PHPBCAT2010 papaya Software GmbH 01.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 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>

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

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

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

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

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

The beautyandthebeast phpbat2010

by Bastian Feder on May 01, 2010

Accessibility

Categories

Tags

Upload Details

Usage Rights

1 Embed 3

Statistics

The beautyandthebeast phpbat2010 — Presentation Transcript