cvs: peardoc /en/chapters standards.xml

danielc Wed May 12 17:57:56 2004 EDT Modified files: /peardoc/en/chapters standards.xml Log: Add sample file.

http://cvs.php.net/diff.php/peardoc/en/chapters/standards.xml?r1=1.11&r2=1.12&ty=u Index: peardoc/en/chapters/standards.xml diff -u peardoc/en/chapters/standards.xml:1.11 peardoc/en/chapters/standards.xml:1.12 --- peardoc/en/chapters/standards.xml:1.11 Sun Mar 14 10:27:25 2004 +++ peardoc/en/chapters/standards.xml Wed May 12 17:57:54 2004 @@ -1,5 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1" ?> -<!-- $Revision: 1.11 $ --> +<!-- $Revision: 1.12 $ --> + <chapter id="standards"> <title>Coding Standards</title> <note> @@ -441,6 +442,235 @@ </sect2> </sect1> + <sect1 id="standards.sample"> + <title>Sample File</title> + <para> + The <command>Id</command> CVS keyword you see in the + example below contains the data for the file used to + create the document you are reading now. When creating + your own PEAR scripts, replace the data there with a + blank keyword: <literal>&dollar;Id:&dollar;</literal> + </para> + <para> + Please take note of the vertical and horizontal spacing. + They are part of the standard. + </para> + <para> + The <quote>fold markers</quote> (<literal>// {{{</literal> and + <literal>// }}}</literal>) are optional. If you aren't using + fold markers, remove <literal>foldmethod=marker</literal> + from the vim header. + </para> + <para> + The example contains many details about writing + Docblock Comments. Following these instructions + is important for two reasons. First, when docblocks + are easy to read, users and developers can quickly + ascertain what your code does. Second, the PEAR + website now contains the phpDocumentor generated + documentation for each release of each package, so + keeping things straight here means the API docs on + the website will be useful. + </para> + <para> + <programlisting role="php"> + <![CDATA[ +<?php +/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4 foldmethod=marker: */ +// +----------------------------------------------------------------------+ +// | PHP version 4 | +// +----------------------------------------------------------------------+ +// | Copyright (c) 1997-2004 The PHP Group | +// +----------------------------------------------------------------------+ +// | This source file is subject to version 3.0 of the PHP license, | +// | that is bundled with this package in the file LICENSE, and is | +// | available through the world-wide-web at the following url: | +// | http://www.php.net/license/3_0.txt. | +// | If you did not receive a copy of the PHP license and are unable to | +// | obtain it through the world-wide-web, please send a note to | +// | license@php.net so we can mail you a copy immediately. | +// +----------------------------------------------------------------------+ +// | Authors: Original Author <author@example.com> | +// | Your Name <you@example.com> | +// +----------------------------------------------------------------------+ +// +// $Id: standards.xml,v 1.12 2004/05/12 21:57:54 danielc Exp $ + +require_once 'PEAR.php'; + +// {{{ constants + +/** + * This is a "Docblock Comment," also known as a "docblock." The class' + * docblock, below, contains a complete description of how to write these. + */ +define('NET_SAMPLE_OK', 1); + +// }}} +// {{{ 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/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 @access + * 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> + * @version $Id: standards.xml,v 1.12 2004/05/12 21:57:54 danielc Exp $ + * @access public + * @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 + */ + var $foo = 'unknown'; + + // }}} + // {{{ setFoo() + + /** + * Registers the status of foo's universe + * + * Summaries for methods should use 3rd person declarative rather + * than 2nd person imperative, begining 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. + * + * @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: + */ + +?> + ]]> + </programlisting> + </para> + </sect1> + </chapter> <!-- Keep this comment at the end of the file Local variables: