Class: Net_Sample

Source Location: /PHP_UML-0.4.2/examples/test5_cs.php

Class Overview

An example of how to write code to PEAR's standards

Author(s):

Original Author <author at example.com>
Another Author <another at example.com>

Version:

Release: @package_version@

Copyright:

1997-2005 The PHP Group

Inherited Variables

Inherited Methods

Class Details

[line 102]
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/docs/HTMLSmartyConverter/default/phpDocumentor/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.

Author: Original Author <author@example.com>
Author: Another Author <another@example.com>
Version: Release: @package_version@
Copyright: 1997-2005 The PHP Group
See: NetOther, Net_Sample::Net_Sample()
Link: http://pear.php.net/package/PackageName
Deprecated: Class deprecated in Release 2.0.0
Since: Class available since Release 1.2.0
License: PHP License 3.0

[ Top ]

Class Variables

$foo = 'unknown'

[line 113]

The status of foo's universe

Potential values are 'good', 'fair', 'poor' and 'unknown'.

Type:

string

[ Top ]

Method Detail

setFoo [line 210]

int setFoo(
string
$arg1, [int
$arg2 = 0])

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

Return: the integer of the set mode used. FALSE if foo foo could not be set.
See: Net_Sample::$foo, Net_Other::someMethod()
Deprecated: Method deprecated in Release 2.0.0
Since: Method available since Release 1.2.0
Throws: exceptionclass [description]
Access: public

Parameters:

string	`$arg1`	—	the string to quote
int	`$arg2`	—	an integer of how many problems happened. Indent to the description's starting point for long ones.

[ Top ]