The Beauty And The Beast Php N W09

The Beauty and the Beast Bastian Feder PHPNW09 papaya Software GmbH 10.10.2009

Me, myself and I  application developer  PHP since 2001  JavaScript since 2002  papaya CMS seit 01.2008 Bastian Feder | papaya Software GmbH 2

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 papayaCMS * @version $Id: index.php 19965 2008-08-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}

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

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

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>

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>AnwendungsdatenSubversion 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=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/talk/view/615)

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 Beauty And The Beast Php N W09

by Bastian Feder on Oct 10, 2009

Accessibility

Categories

Tags

Upload Details

Usage Rights

1 Embed 1

Statistics

The Beauty And The Beast Php N W09 — Presentation Transcript