Manuel Pear

Niveau superieur
Sommaire

Fichier d'exemple (incluant les standarts Docblock pour les commentaires)

Les sources des paquetages PEAR sont lues par des centaines d'utilisateurs. Il se peut aussi que d'autres personnes participent à votre paquetage dans le futur. C'est pour cela qu'il est important de faciliter la vie de tout le monde en formatant le code et les commentaires en respectant les standards. Les autres personnes pourront ainsi rapidement trouver les informations qu'elles cherchent puisqu'elles seront au bon endroit. Votre coopération sera appréciée.

Chaque bloc de commentaire dans l'exemple contient plusieurs détails concernant la rédaction des blocs de commentaires. Le respect de ces instructions est important pour deux raisons. D'un côté, lorsque les commentaires sont lisibles, les utilisateurs et les développeurs peuvent comprendre rapidement ce que votre code fait. D'un autre côté, le site web de PEAR contient maintenant les documentations générées avec phpDocumentor pour chaque release de chaque paquetage, bien formater vos commentaires signifie que la documentation des API sera utilisable.

Merci de prendre soin des espacements verticaux et horizontaux. Ils font aussi partie du standard.

Les << délimitateurs >> (// {{{ et // }}}) sont optionnels. Si vous ne les utilisez pas, supprimez foldmethod=marker de la configuration de vim.

  1. <?php
  2.  
  3. /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */  
  4.  
  5. /**
  6. * Description courte du fichier
  7. *
  8. * Description longue du fichier (si existante)...
  9. *
  10. * PHP versions 4 and 5
  11. *
  12. * LICENSE: This source file is subject to version 3.0 of the PHP license
  13. * that is available through the world-wide-web at the following URI:
  14. * http://www.php.net/license/3_0.txt. If you did not receive a copy of
  15. * the PHP License and are unable to obtain it through the web, please
  16. * send a note to license@php.net so we can mail you a copy immediately.
  17. *
  18. * @category NomCategorie
  19. * @package   NomPaquetage
  20. * @author    Auteur Original <author@example.com>
  21. * @author    Un autre auteur <another@example.com>
  22. * @copyright 1997-2005 The PHP Group
  23. * @license   http://www.php.net/license/3_0.txt PHP License 3.0
  24. * @version   CVS: $Id:$
  25. * @link    http://pear.php.net/package/NomPaquetage
  26. * @see      NetOther, Net_Sample::Net_Sample()
  27. * @since    File available since Release 1.2.0
  28. * @deprecated File deprecated in Release 2.0.0
  29. */  
  30.  
  31. /**
  32. * Ceci est un commentaire "Docblock Comment" aussi connu sous le nom de
  33. * "docblock.
  34. * La classe docblock, plus bas, vous montre un exemple complet
  35. * d'utilisation.
  36. */  
  37. require_once 'PEAR.php';  
  38.  
  39. // {{{ constants
  40.  
  41. /**
  42. * Valeur de retour des méthodes si elle réusissent.
  43. */  
  44. define('NET_SAMPLE_OK', 1);  
  45.  
  46. // }}}
  47. // {{{ GLOBALS
  48.  
  49. /**
  50. * Nombre d'objets créés.
  51. * @global int $GLOBALS['_NET_SAMPLE_Count']
  52. */  
  53. $GLOBALS['_NET_SAMPLE_Count'] = 0;  
  54.  
  55. // }}}
  56. // {{{ Net_Sample
  57.  
  58. /**
  59. * An example of how to write code to PEAR's standards
  60. *
  61. * Docblock comments start with "/**" at the top. Notice how the "/"
  62. * lines up with the normal indenting and the asterisks on subsequent rows
  63. * are in line with the first asterisk. The last line of comment text
  64. * should be immediately followed on the next line by the closing asterisk
  65. * and slash and then the item you are commenting on should be on the next
  66. * line below that. Don't add extra lines. Please put a blank line
  67. * between paragraphs as well as between the end of the description and
  68. * the start of the @tags. Wrap comments before 80 columns in order to
  69. * ease readability for a wide variety of users.
  70. *
  71. * Docblocks can only be used for programming constructs which allow them
  72. * (classes, properties, methods, defines, includes, globals). See the
  73. * phpDocumentor documentation for more information.
  74. * http://phpdoc.org/docs/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html
  75. *
  76. * The Javadoc Style Guide is an excellent resource for figuring out
  77. * how to say what needs to be said in docblock comments. Much of what is
  78. * written here is a summary of what is found there, though there are some
  79. * cases where what's said here overrides what is said there.
  80. * http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#styleguide
  81. *
  82. * The first line of any docblock is the summary. Make them one short
  83. * sentence, without a period at the end. Summaries for classes, properties
  84. * and constants should omit the subject and simply state the object,
  85. * because they are describing things rather than actions or behaviors.
  86. *
  87. * Below are the tags commonly used for classes. @category through @version
  88. * are required. The remainder should only be used when necessary.
  89. * Please use them in the order they appear here. phpDocumentor has
  90. * several other tags available, feel free to use them.
  91. *
  92. * @category CategoryName
  93. * @package   PackageName
  94. * @author    Original Author <author@example.com>
  95. * @author    Another Author <another@example.com>
  96. * @copyright 1997-2005 The PHP Group
  97. * @license   http://www.php.net/license/3_0.txt PHP License 3.0
  98. * @version   Release: @package_version@
  99. * @link    http://pear.php.net/package/PackageName
  100. * @see      NetOther, Net_Sample::Net_Sample()
  101. * @since    Class available since Release 1.2.0
  102. * @deprecated Class deprecated in Release 2.0.0
  103. */  
  104. class Net_Sample  
  105. { 
  106.    // {{{ properties
  107.  
  108.    /**
  109.     * The status of foo's universe
  110.     *
  111.     * Potential values are 'good', 'fair', 'poor' and 'unknown'.
  112.     *
  113.     * @var string
  114.     */ 
  115.    var $foo = 'unknown'; 
  116.  
  117.    /**
  118.     * The status of life
  119.     *
  120.     * Note that names of private properties or methods must be
  121.     * preceeded by an underscore.
  122.     *
  123.     * @var bool
  124.     * @access private
  125.     */ 
  126.    var $_good = true; 
  127.  
  128.    // }}}
  129.    // {{{ setFoo()
  130.  
  131.    /**
  132.     * Registers the status of foo's universe
  133.     *
  134.     * Summaries for methods should use 3rd person declarative rather
  135.     * than 2nd person imperative, begining with a verb phrase.
  136.     *
  137.     * Summaries should add description beyond the method's name. The
  138.     * best method names are "self-documenting", meaning they tell you
  139.     * basically what the method does. If the summary merely repeats
  140.     * the method name in sentence form, it is not providing more
  141.     * information.
  142.     *
  143.     * Summary Examples:
  144.     * + Sets the label          (preferred)
  145.     * + Set the label          (avoid)
  146.     * + This method sets the label (avoid)
  147.     *
  148.     * Below are the tags commonly used for methods. A @param tag is
  149.     * required for each parameter the method has. The @return and
  150.     * @access tags are mandatory. The @throws tag is required if the
  151.     * method uses exceptions. @static is required if the method can
  152.     * be called statically. The remainder should only be used when
  153.     * necessary. Please use them in the order they appear here.
  154.     * phpDocumentor has several other tags available, feel free to use
  155.     * them.
  156.     *
  157.     * The @param tag contains the data type, then the parameter's
  158.     * name, followed by a description. By convention, the first noun in
  159.     * the description is the data type of the parameter. Articles like
  160.     * "a", "an", and "the" can precede the noun. The descriptions
  161.     * should start with a phrase. If further description is necessary,
  162.     * follow with sentences. Having two spaces between the name and the
  163.     * description aids readability.
  164.     *
  165.     * When writing a phrase, do not capitalize and do not end with a
  166.     * period:
  167.     * + the string to be tested
  168.     *
  169.     * When writing a phrase followed by a sentence, do not capitalize the
  170.     * phrase, but end it with a period to distinguish it from the start
  171.     * of the next sentence:
  172.     * + the string to be tested. Must use UTF-8 encoding.
  173.     *
  174.     * Return tags should contain the data type then a description of
  175.     * the data returned. The data type can be any of PHP's data types
  176.     * (int, float, bool, string, array, object, resource, mixed)
  177.     * and should contain the type primarily returned. For example, if
  178.     * a method returns an object when things work correctly but false
  179.     * when an error happens, say 'object' rather than 'mixed.' Use
  180.     * 'void' if nothing is returned.
  181.     *
  182.     * Here's an example of how to format examples:
  183.     * <code>
  184.     * require_once 'Net/Sample.php';
  185.     *
  186.     * $s = new Net_Sample();
  187.     * if (PEAR::isError($s)) {
  188.     *    echo $s->getMessage() . "\n";
  189.     * }
  190.     * </code>
  191.     *
  192.     * Here is an example for non-php example or sample:
  193.     * <samp>
  194.     * pear install net_sample
  195.     * </samp>
  196.     *
  197.     * @param string $arg1 the string to quote
  198.     * @param int   $arg2 an integer of how many problems happened.
  199.     *                Indent to the description's starting point
  200.     *                for long ones.
  201.     *
  202.     * @return int the integer of the set mode used. FALSE if foo
  203.     *          foo could not be set.
  204.     * @throws exceptionclass [description]
  205.     *
  206.     * @access public
  207.     * @static
  208.     * @see Net_Sample::$foo, Net_Other::someMethod()
  209.     * @since Method available since Release 1.2.0
  210.     * @deprecated Method deprecated in Release 2.0.0
  211.     */ 
  212.    function setFoo($arg1, $arg2 = 0) 
  213.    { 
  214.       /*
  215.        * This is a "Block Comment." The format is the same as
  216.        * Docblock Comments except there is only one asterisk at the
  217.        * top. phpDocumentor doesn't parse these.
  218.        */ 
  219.       if ($arg1 == 'good' || $arg1 == 'fair') { 
  220.          $this->foo = $arg1; 
  221.          return 1; 
  222.       } elseif ($arg1 == 'poor' && $arg2 > 1) { 
  223.          $this->foo = 'poor'; 
  224.          return 2; 
  225.       } else { 
  226.          return false; 
  227.       } 
  228.    } 
  229.  
  230.    // }}}
  231. }  
  232.  
  233. // }}}
  234.  
  235. /*
  236. * Local variables:
  237. * tab-width: 4
  238. * c-basic-offset: 4
  239. * c-hanging-comment-ender-p: nil
  240. * End:
  241. */  
  242.  
  243.  
  244. ?> 
Niveau superieur
Sommaire

Remonter Remonter
L'éditeur javascript - CSS - Gentoo - Tutoriaux PHP - Tutoriels PHP - Bretagne - php - Moto - Kit graphique