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.
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. 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. 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. 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. Quality check
error log
(errors.html in root of API documentation)
todo list
(todolist.html in root of API documentation)
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. 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.
17. external Tools framework
Enables Eclipse to run ‚stand-alone‘
applications
Two broad classes of external tools are
available:
▹ Ant build files
▹ Everything else
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. How to integrate (III)
Display in favorites
menu
Standard Input and
Output
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