Expert PHP 5 Tools phần 3 doc

Chapter 2 [ 77 ] @method Name: File: Class: Method: Property: @method return_type method_name(type $arg1[ = val1], type $arg2[ = val2], …) [description] [x] Example(s): /** * @method array mix(Array array1 = array(), Array array2 = array()) joins and randomizes two arrays */ Comments: This is an extremely useful tag for any developer who takes advantage of PHP's magic methods. Since even reection cannot know about methods the developer creates using the __call() magic method, one can use the @method tag to document any magic methods provided by the class. Any method documented this way will be listed on the class-level documentation. @name Name: File: Class: Method: Property: @name $var_name [x] Example(s): /** * @name $colors * @global array */ $HTML_COLORS = array('#ffffff' => 'white', '#ff0000' => 'red' '#000000' => 'black'); Comments: Creates an alias for a global variable for documentation purposes (also see @global tag). Download from Wow! eBook www.WoweBook.com Documentation with phpDocumentor [ 78 ] @package Name: File: Class: Method: Property: @package package_name x x Example(s): /** * File-level package tag * @package Authentication_API */ /** * Class-level package tag (needed because it is not inherited!!!) * @package Authentication_API */ class ResultSet { } Comments: This tag denes a logical grouping of elements within the documentation. A le-level @package tag will apply to all elements within that le; however, package membership of classes will be default unless explicitly set for the class itself. This is true even if the le-level package tag has been set! The only exception is that sub-classes inherit their parent class's package membership. @property Name: File: Class: Method: Property: @property data_type $var_name [description] @property-read datatype $varname [description] @property-write datatype $varname [description] [x] [x] [x] Example(s): /** * @property string $greeting greeting to user upon login */ class Login { private $greeting = 'Hello, Stranger!'; public function __get($property) { if ($property == 'greeting') { return $this->greeting; } } } Download from Wow! eBook www.WoweBook.com Chapter 2 [ 79 ] Comments: The @property tag documents "magic" properties made available by a class's __get() and __set() methods. In contrast the @property-read and @property-write tags are used to document magic properties that are readable or writable only, respectively. @return Name: File: Class: Method: Property: @return data_type x Example(s): /** * @return int */ Comments: This tag indicates the data type of the return value of the method. Valid data types are native PHP data types (int, string, and so on), array, class names, null, and nothing (void). It is possible to list multiple possible data types separated by the pipe character ("|"): array|string. @see Name: File: Class: Method: Property: Usage 1: @see [ClassName::]methodName() Usage 2: @see [ClassName::]$property_name Usage 3: @see php_function_name [x] [x] [x] [x] [x] [x] [x] [x] [x] [x] [x] [x] Example(s): /** * Usage 1: link to documentation of method in another class * @see DbConnection::connect() * Usage 2: link to a property in this class * @see $greeting * Usage 3: link to a PHP built-in function * @see mysql_connect() Comments: This tag allows you to link to other sections of your documentation. This tag is very important because it allows readers of your documentation to follow a logical ow. In a sense it is as empowering to documentation as hyperlinks are to the Web in general. You can specify names of classes and the properties and methods inside those classes. The string '::' is used to separated class name from property/methods name. Use @link, @inline, or {@link} for creating hyperlinks to external resources. Download from Wow! eBook www.WoweBook.com Documentation with phpDocumentor [ 80 ] @since Name: File: Class: Method: Property: @since [version_info] x x [x] [x] Example(s): /** * @since r0.9.2 */ Comments: This tag is used to indicate at which revision or version of the software this element was added. The version info string can identify the revision/version within your source code control system or it can be the ofcial release of the software in which the element was rst available to the users. @static Name: File: Class: Method: Property: @static [x] [x] Example(s): /** * @static */ public static function proprietaryEncode() { } Comments: This tag is used to document static properties and methods. @staticvar Name: File: Class: Method: Property: @staticvar data_type [description] [x] Example(s): /** * @staticvar bool determines whether this object needs updating */ public function checkState() { if (self::current === false) { echo "Update me!"; } } Download from Wow! eBook www.WoweBook.com Chapter 2 [ 81 ] Comments: This tag is used to indicate when a method uses a static property. @subpackage Name: File: Class: Method: Property: @subpackage [x] [x] Example(s): /** * @package World_Domination * @subpackage Conquer_Europe */ class Attack { } Comments: This tag is used to further organize the les and classes in your documentation by assigning them to sub-packages. The @subpackage tag cannot be used without the @package tag in the same DocBlock. @todo Name: File: Class: Method: Property: @todo description [x] [x] [x] [x] Example(s): /** * @todo refactor to improve performance */ public function sortComplexData() { } Comments: This tag is used to leave a note for the developer(s) to implement future changes or enhancements. Download from Wow! eBook www.WoweBook.com Documentation with phpDocumentor [ 82 ] @tutorial Name: File: Class: Method: Property: @tutorial tutorial_name [x] [x] Example(s): /** * @package Killer_App * @tutorial Killer_App.pkg */ class AwesomeFeature { } Comments: This tag links to tutorials dened within your documentation. Tutorials follow certain naming conventions and are written in DocBook syntax. See the section on phpDocumentor tutorials for more information. To create a hyperlink to external resources, use the @see, @link, or inline {@link} tags instead. @uses Name: File: Class: Method: Property: @uses [ClassName::]methodName() description [x] [x] [x] [x] Example(s): /** * @uses Utility::secretAlgorithm() seeds algorithm with special salt */ class Shuffle { } Comments: This tag behaves exactly like the @see tag with two differences. First, a reciprocal @usedby tag in the DocBlock of the element that is being pointed to. Second, unlike @see, @uses takes a description. @var Name: File: Class: Method: Property: @var data_type [description] [x] Example(s): /** * @var string full user name for logging purposes */ $uname = 'Dirk Merkel'; Download from Wow! eBook www.WoweBook.com Chapter 2 [ 83 ] Comments: This tag is used to document the data type of variables and properties. It also takes an optional description that can be used to elaborate on the content and/or use of the property. @version Name: File: Class: Method: Property: @version version_string [x] [x] [x] Example(s): /** * @version v2.3b – prerelease candidate */ Comments: You can use this tag to record your own versioning. A common use if this tag is to put a placeholder that will automatically be replaced by the version control system's revision or version number upon committing the change (see the chapter on source code control for more detail). Inline tags Inline tags differ from standard text in that they can occur anywhere within the text of the short or long description of a DocBlock. To properly differentiate inline tags from the description, their syntax differs a bit from standard tags in that they are enclosed by curly brackets. When parsed by phpDocumentor and rendered by the desired converter, these tags are replaced by content that is being placed inline with the rest of the text. In addition to DocBlock descriptions, inline tags can be used in tutorials. There are a total of six inline tags, four of which can be used in DocBlocks and a different set of four can be used in tutorials. Download from Wow! eBook www.WoweBook.com Documentation with phpDocumentor [ 84 ] {@Example} Name: File: Class: Method: Property: {@example start_line end_line} [x] [x] [x] Context: DocBlock: Tutorial: [x] Example(s): /** * Authentication login method * * Before being able to access the web services API, * a client has to authenticate via this login method. * Simplified client code might look like this: * {@example examples/login.php 0 15} */ public function login($login, $password) { } Comments: The inline {@example} tag behaves very much like the standard @example tag in that it retrieves, parses, and displays all or part of a source code le with highlighted syntax. See the description of the @example tag for details on which les are compatible and how to reference them. The differences from the standard @example tag is that the referenced source code will be displayed inline and that it is possible to limit the listing by start and end line number within the le. Download from Wow! eBook www.WoweBook.com Chapter 2 [ 85 ] {@id} Name: File: Class: Method: Property: {@id section_name} Context: DocBlock: Tutorial: [x] Example(s): // in DocBook tutorial <refentry id="{@id my_main_section}"> <refsect1 id="{@id main_argument}"> </refsect1> <refentry> // tutorial tag /** * @tutorial WebServices.Authentication.Login.cls.main_section. main_argument */ Comments: When using a @tutorial tag to link to a particular tutorial, it is possible to directly link to specic sections within the referenced document. The {@id} tag allows one to assign the desired section an identier that can be used in the link. The general structure of building a link to a sub-section of a tutorial looks like this: package.package_name[.sub-package_name].file[.section_name]. [sub-section_name] Download from Wow! eBook www.WoweBook.com Documentation with phpDocumentor [ 86 ] {@internal}} Name: File: Class: Method: Property: {@internal}} [x] [x] [x] [x] Context: DocBlock: Tutorial: [x] Example(s): /** * Web Services Authentication * * Use this class and its methods to obtain an authentication * token that will be used during the session. {@internal This * must be discussed with the architectural committee. See * our {@link http://massivecorp.com/gl.html Massive Corp * Development Guidelines}.}} */ class Authentication { } Comments: Analogous to the standard @internal tag, the inline {@internal}} tag prevents the corresponding content from being included in the documentation unless the pp / parseprivate command line switch is being used. This has the same effect as setting the @access tag to private and serves the purpose of creating documentation for different audiences. Note: This tag ends in two closing curly brackets, which is necessary because itself can contain inline tags. Download from Wow! eBook www.WoweBook.com [...]... @sourcereview 03- 15- 2009 by Kimba Merkel */ class SuperSecretAlgorithm { } Now all you have to do for phpDocumentor to recognize the new tag is to include this option on the command line: customtags sourcereview Alternatively, you can define your custom tag(s) in your own config file Summary If the example in this chapter did not sell you on the benefits of documenting your code using the phpDoc syntax,... corresponding lines The first line of the documented element is considered line 1 Omitting the ending line number will list the element's source code from the starting line to the end of the listing [ 89 ] Download from Wow! eBook www.WoweBook.com Documentation with phpDocumentor {@toc} Name: File: Class: Method: Property: {@toc} Context: DocBlock: Tutorial: [x] Example(s): // in DocBook tutorial . eBook www.WoweBook.com Documentation with phpDocumentor [ 90 ] {@toc} Name: File: Class: Method: Property: {@toc} Context: DocBlock: Tutorial: [x] Example(s): // in DocBook tutorial <refentry. did not sell you on the benets of documenting your code using the phpDoc syntax, you only need to take a look at the API documentation of some of the biggest PHP projects out there, such as Zend. eBook www.WoweBook.com Documentation with phpDocumentor [ 84 ] {@Example} Name: File: Class: Method: Property: {@example start_line end_line} [x] [x] [x] Context: DocBlock: Tutorial: [x] Example(s): /** *