PHP Function Comments
Functions:
/** * Does something interesting * * @param Place $where Where something interesting takes place * @param integer $repeat How many times something interesting should happen * * @throws Some_Exception_Class If something interesting cannot happen * @author Monkey Coder <mcoder@facebook.com> * @return Status */ Classes:
/** * Short description for class * * Long description for class (if any)... * * @copyright 2006 Zend Technologies * @license http://www.zend.com/license/3_0.txt PHP License 3.0 * @version Release: @package_version@ * @link http://dev.zend.com/package/PackageName * @since Class available since Release 1.2.0 */ Sample File:
<?php/** * Short description for file * * Long description for file (if any)... * * PHP version 5.6 * * LICENSE: This source file is subject to version 3.01 of the PHP license * that is available through the world-wide-web at the following URI: * http://www.php.net/license/3_01.txt. If you did not receive a copy of * the PHP License and are unable to obtain it through the web, please * send a note to license@php.net so we can mail you a copy immediately. * * @category CategoryName * @package PackageName * @author Original Author <author@example.com> * @author Another Author <another@example.com> * @copyright 1997-2005 The PHP Group * @license http://www.php.net/license/3_01.txt PHP License 3.01 * @version SVN: $Id$ * @link http://pear.php.net/package/PackageName * @see NetOther, Net_Sample::Net_Sample() * @since File available since Release 1.2.0 * @deprecated File deprecated in Release 2.0.0 *//** * This is a "Docblock Comment," also known as a "docblock." The class' * docblock, below, contains a complete description of how to write these. */require_once 'PEAR.php';// {{{ constants/** * Methods return this if they succeed */define('NET_SAMPLE_OK', 1);// }}}// {{{ GLOBALS/** * The number of objects created * @global int $GLOBALS['_NET_SAMPLE_Count'] */$GLOBALS['_NET_SAMPLE_Count'] = 0;// }}}// {{{ Net_Sample/** * An example of how to write code to PEAR's standards * * Docblock comments start with "/**" at the top. Notice how the "/" * lines up with the normal indenting and the asterisks on subsequent rows * are in line with the first asterisk. The last line of comment text * should be immediately followed on the next line by the closing asterisk * and slash and then the item you are commenting on should be on the next * line below that. Don't add extra lines. Please put a blank line * between paragraphs as well as between the end of the description and * the start of the @tags. Wrap comments before 80 columns in order to * ease readability for a wide variety of users. * * Docblocks can only be used for programming constructs which allow them * (classes, properties, methods, defines, includes, globals). See the * phpDocumentor documentation for more information. * http://phpdoc.org/tutorial_phpDocumentor.howto.pkg.html * * The Javadoc Style Guide is an excellent resource for figuring out * how to say what needs to be said in docblock comments. Much of what is * written here is a summary of what is found there, though there are some * cases where what's said here overrides what is said there. * http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide * * The first line of any docblock is the summary. Make them one short * sentence, without a period at the end. Summaries for classes, properties * and constants should omit the subject and simply state the object, * because they are describing things rather than actions or behaviors. * * Below are the tags commonly used for classes. @category through @version * are required. The remainder should only be used when necessary. * Please use them in the order they appear here. phpDocumentor has * several other tags available, feel free to use them. * * @category CategoryName * @package PackageName * @author Original Author <author@example.com> * @author Another Author <another@example.com> * @copyright 1997-2005 The PHP Group * @license http://www.php.net/license/3_01.txt PHP License 3.01 * @version Release: @package_version@ * @link http://pear.php.net/package/PackageName * @see NetOther, Net_Sample::Net_Sample() * @since Class available since Release 1.2.0 * @deprecated Class deprecated in Release 2.0.0 */class Net_Sample{ // {{{ properties /** * The status of foo's universe * Potential values are 'good', 'fair', 'poor' and 'unknown'. * @var string $foo */ public $foo = 'unknown'; /** * The status of life * Note that names of private properties or methods must be * preceeded by an underscore. * @var bool $_good */ private $_good = true; // }}} // {{{ setFoo() /** * Registers the status of foo's universe * * Summaries for methods should use 3rd person declarative rather * than 2nd person imperative, beginning with a verb phrase. * * Summaries should add description beyond the method's name. The * best method names are "self-documenting", meaning they tell you * basically what the method does. If the summary merely repeats * the method name in sentence form, it is not providing more * information. * * Summary Examples: * + Sets the label (preferred) * + Set the label (avoid) * + This method sets the label (avoid) * * Below are the tags commonly used for methods. A @param tag is * required for each parameter the method has. The @return * and @access tags are mandatory. The @throws tag is required if * the method uses exceptions. @static is required if the method can * be called statically. The remainder should only be used when * necessary. Please use them in the order they appear here. * phpDocumentor has several other tags available, feel free to use * them. * * The @param tag contains the data type, then the parameter's * name, followed by a description. By convention, the first noun in * the description is the data type of the parameter. Articles like * "a", "an", and "the" can precede the noun. The descriptions * should start with a phrase. If further description is necessary, * follow with sentences. Having two spaces between the name and the * description aids readability. * * When writing a phrase, do not capitalize and do not end with a * period: * + the string to be tested * * When writing a phrase followed by a sentence, do not capitalize the * phrase, but end it with a period to distinguish it from the start * of the next sentence: * + the string to be tested. Must use UTF-8 encoding. * * Return tags should contain the data type then a description of * the data returned. The data type can be any of PHP's data types * (int, float, bool, string, array, object, resource, mixed) * and should contain the type primarily returned. For example, if * a method returns an object when things work correctly but false * when an error happens, say 'object' rather than 'mixed.' Use * 'void' if nothing is returned. * * Here's an example of how to format examples: * <code> * require_once 'Net/Sample.php'; * * $s = new Net_Sample(); * if (PEAR::isError($s)) { * echo $s->getMessage() . "\n"; * } * </code> * * Here is an example for non-php example or sample: * <samp> * pear install net_sample * </samp> * * @param string $arg1 the string to quote * @param int $arg2 an integer of how many problems happened. * Indent to the description's starting point * for long ones. * * @return int the integer of the set mode used. FALSE if foo * foo could not be set. * @throws exceptionclass [description] * * @access public * @static * @see Net_Sample::$foo, Net_Other::someMethod() * @since Method available since Release 1.2.0 * @deprecated Method deprecated in Release 2.0.0 */ function setFoo($arg1, $arg2 = 0) { /* * This is a "Block Comment." The format is the same as * Docblock Comments except there is only one asterisk at the * top. phpDocumentor doesn't parse these. */ if ($arg1 == 'good' || $arg1 == 'fair') { $this->foo = $arg1; return 1; } elseif ($arg1 == 'poor' && $arg2 > 1) { $this->foo = 'poor'; return 2; } else { return false; } } // }}}}// }}}/* * Local variables: * tab-width: 4 * c-basic-offset: 4 * c-hanging-comment-ender-p: nil * End: */?>Source: PEAR Docblock Comment standards