The beautyandthebeast phpbat2010
Upcoming SlideShare
Loading in...5
×
 

Like this? Share it with your network

Share

The beautyandthebeast phpbat2010

on

  • 1,930 views

Von Entwicklern zu tiefst verachtet und in vielen Situationen dennoch heiß geliebt, ist eine ausführliche Dokumentation des Quellcodes. Grade, wenn es um die Anpassung und/oder Erweiterung von ...

Von Entwicklern zu tiefst verachtet und in vielen Situationen dennoch heiß geliebt, ist eine ausführliche Dokumentation des Quellcodes. Grade, wenn es um die Anpassung und/oder Erweiterung von legacy Code geht, wird der Ruf nach Dokumentation laut.
PhpDocumentor ist eines von vielen Tools, die uns Entwicklern das dokumentatorische Leben etwas leichter machen können. Es scannt den Quellcode nach Annotationen, Vererbungen, etc. und generiert strukturierte Dokumentationen daraus.
Dieser Vortrag stellt PhpDocumentor im Detail vor und geht nicht nur auf die zahlreichen Möglichkeiten dieses Tools ein, sondern zeigt detailliert anhand von Beispielen, wie diese optimal eingesetzt werden können.

Statistics

Views

Total Views
1,930
Views on SlideShare
1,927
Embed Views
3

Actions

Likes
0
Downloads
8
Comments
0

1 Embed 3

http://www.slideshare.net 3

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

CC Attribution-NonCommercial-ShareAlike LicenseCC Attribution-NonCommercial-ShareAlike LicenseCC Attribution-NonCommercial-ShareAlike License

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

The beautyandthebeast phpbat2010 Presentation Transcript

  • 1. The Beauty and the Beast Bastian Feder PHPBCAT2010 papaya Software GmbH 01.05.2010
  • 2. Me, myself and I  application developer  PHP since 2001  JavaScript since 2002  papaya CMS seit 01.2008
  • 3. Who are you?
  • 4. 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.
  • 5. What is this phpDocumentor? ● Automated documentation ● Identifies annotations (tags) ● Command line tool ● Written in PHP ● Converters render different formats (HTML, Smarty, DocBook, etc)
  • 6. 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.
  • 7. Tags - examples ● @package, @subpackage, @category ● @author, @license, @version ● @param, @return ● @access ● @see, @link, @uses ● @todo ● @example, @tutorial
  • 8. 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; }
  • 9. 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 $ */
  • 10. 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}
  • 11. 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 ...
  • 12. User conifguration file ● Templates in subdir 'user' ● Covers complete configuration options ● Additional description each option $> phpdoc -c PATH/TO/myConf.ini
  • 13. Generated documentation
  • 14. 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
  • 15. Tutorials – types ● Package tutorials ● File extension: .pkg ● Class tutorials ● File extension: .cls ● Procedural code tutorials ● File extension: .proc
  • 16. 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 */
  • 17. 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>
  • 18. Tutorials – generated output
  • 19. Quality check ● Error log (errors.html in root of API documentation) ● Todo list (todolist.html in root of API documentation)
  • 20. 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 $
  • 21. SVN / CVS identifier (II) ● Location of 'config' – file: ● MacOsX/Linux: ~/.subversion/config ● WinXp: C:Dokumente und Einstellungen <USER>AnwendungsdatenSubversionconf ig
  • 22. 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
  • 23. 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;
  • 24. 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.
  • 25. 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 */
  • 26. Eclipse PDT – docu hints
  • 27. external Tools framework ● Enables Eclipse to run ‚stand-alone‘ applications ● Two broad classes of external tools are available: ● Ant build files ● Everything else
  • 28. How to integrate
  • 29. 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.
  • 30. How to integrate (III) ● Display in favorites menu ● Standard Input and Output
  • 31. Any questions left?
  • 32. Slides'n Feedback ● Sildes (http://www.slideshare.net/lapistano) ● Feedback ● Personal contact (conference@bastian-feder.de) ● Joind'in (http://joind.in/user/view/557)
  • 33. 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)
  • 34. 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