PHP 函数注释 - 开卷题库

小开

最佳答案

这是 PHPDoc语法。

阅读更多: 译自: 美国《科学》杂志网站(http://www.phpdoc.org/)原著: http://www.phpdoc.org/

小开

职能:

/**
* 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
*/

课程:

/**
* 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
*/

示例文件:

<?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:
*/


?>

资料来源: 评论标准

小开

您可以通过使用 RefectionMethod 类和调用-> getDoccomments ()来获取特定方法的注释。

Http://www.php.net/manual/en/reflectionclass.getdoccomment.php

小开

你必须检查这个: Docblock 评论标准

示例文件(包括 Docblock 注释标准)