PHP Starter Day 2008


                          PHPDocumentor
                       The Beauty and the Beast




Bastian...
Me, myself & I
       application developer
       PHP seit 2001
       papaya CMS seit
        01.2008
Agenda
   phpDocumentor tags
   The DocBlock
   SVN
   Additional features
   Eclipse PDT
    ▹   Documentation hints...
phpDocumentor tags
   a phpDocumentor tag is an annotation telling a
    parser what to do with the given information.
 ...
phpDocumentor tags       (examples)

   @package, @subpackage, @category
   @author, @license, @version
   @param, @ret...
DocBlock definition
/**
* This is an example short description of a phpDocumentor DocBlock.
*
* This example shall show ho...
DocBlock inheritence
   @author, @version, and @copyright are automatically
    inherited unless explicitly specified in ...
Additional features
                                    (inline{} tags)

   display their information in the text flow


...
Additional features
                           (tutorials)

   ability to link in external documentation
   hooks are th...
Quality check
   error log
    (errors.html in root of API documentation)
   todo list
    (todolist.html in root of API...
SVN / CVS identifier
   $Date: $
    ▹   $Date: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $
   $Revision: $
    ▹   $...
SVN / CVS identifier (II)
   Location of 'config' – file:
    ▹   MacOsX/Linux:
        ~/.subversion/config
    ▹   WinX...
SVN / CVS identifier (III)
       add following lines to configuration file:

[miscellany]
global-ignores = *.o *.lo *.la...
Eclipse PDT – docu hints
if you plan to instantiate a new object in your
  class, declare the name of the class to be
  in...
Eclipse PDT – docu hints
   once you declared the complete function
    DocBlock, Eclipse is able to show you these
    i...
Eclipse PDT – docu hints
external Tools framework
   Enables Eclipse to run ‚stand-alone‘
    applications
   Two broad classes of external tools...
How to integrate
How to integrate (II)
   Location
    points to the phpDocumentor installation

   Working Directory
    directory to st...
How to integrate (III)
   Display in favorites
    menu

   Standard Input and
    Output
References

    phpDocumentor website @ pear.php.net
    (http://pear.php.net/package/PhpDocumentor/docs/1.4.2)

   SVN ...
License
   This set of slides and the source code included
    in the download package is licensed under the

    Creativ...
Upcoming SlideShare
Loading in...5
×

Php Documentor The Beauty And The Beast

5,871

Published on

This presentation givs a short overview about phpDocumentor and shows how to use it inside Eclipse PDT

Published in: Technology
0 Comments
5 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
5,871
On Slideshare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
34
Comments
0
Likes
5
Embeds 0
No embeds

No notes for slide

Php Documentor The Beauty And The Beast

  1. 1. PHP Starter Day 2008 PHPDocumentor The Beauty and the Beast Bastian Feder papaya Software GmbH 27.10.2008
  2. 2. Me, myself & I  application developer  PHP seit 2001  papaya CMS seit 01.2008
  3. 3. Agenda  phpDocumentor tags  The DocBlock  SVN  Additional features  Eclipse PDT ▹ Documentation hints ▹ Integrate phpDocumentor  References
  4. 4. 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.
  5. 5. phpDocumentor tags (examples)  @package, @subpackage, @category  @author, @license, @version  @param, @return  @access  @see, @link, @uses  @todo
  6. 6. 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. * * @author Thomas Weinert <info@papaya-cms.com> * @package papaya * @version $Id: index.php 19965 2008-08-11 12:23:29Z rekowski $ */
  7. 7. 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}
  8. 8. Additional features (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 quot;{@linkquot; in a docblock, I just use quot;{@}link.quot; If * I want the characters quot;{@*}quot; I use quot;{@}*}quot; */ function bar() { return; }
  9. 9. Additional features (tutorials)  ability to link in external documentation  hooks are the inline{} tags  enable rendering the tutorial: ▹ existing subdir named „tutorials“ ▹ comandline switch „-d“, „--directory“, „-f“ or „-- filename“ must contain the subdir
  10. 10. Quality check  error log (errors.html in root of API documentation)  todo list (todolist.html in root of API documentation)
  11. 11. 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 $
  12. 12. SVN / CVS identifier (II)  Location of 'config' – file: ▹ MacOsX/Linux: ~/.subversion/config ▹ WinXp: C:Dokumente und Einstellungen <USER>AnwendungsdatenSubversionconfig
  13. 13. 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=LastChangedDate LastChangedRevision URL *.htm = svn:eol-style=LF;svn:mime-type=text/html;svn:keywords=LastChangedDate LastChangedRevision 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
  14. 14. 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;
  15. 15. Eclipse PDT – docu hints  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.
  16. 16. Eclipse PDT – docu hints
  17. 17. external Tools framework  Enables Eclipse to run ‚stand-alone‘ applications  Two broad classes of external tools are available: ▹ Ant build files ▹ Everything else
  18. 18. How to integrate
  19. 19. 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.
  20. 20. How to integrate (III)  Display in favorites menu  Standard Input and Output
  21. 21. References  phpDocumentor website @ pear.php.net (http://pear.php.net/package/PhpDocumentor/docs/1.4.2)  SVN keyword substitution (http://svnbook.red-bean.com/en/1.4/svn-book.html#svn.advanced.props.special.keywords)
  22. 22. 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
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×