cvs: peardoc /en/chapters rfcs-entities.xml /en/chapters/rfcs header-comments.xml version-naming.xml

http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs-entities.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/chapters/rfcs-entities.xml
diff -u peardoc/en/chapters/rfcs-entities.xml:1.2 peardoc/en/chapters/rfcs-entities.xml:1.3
--- peardoc/en/chapters/rfcs-entities.xml:1.2	Sun May  3 13:21:22 2009
+++ peardoc/en/chapters/rfcs-entities.xml	Sun May  3 16:56:43 2009
@@ -1,2 +1,3 @@
 &chapters.rfcs.error-handling;
+&chapters.rfcs.header-comments;
 &chapters.rfcs.version-naming;
http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs/version-naming.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/chapters/rfcs/version-naming.xml
diff -u peardoc/en/chapters/rfcs/version-naming.xml:1.2 peardoc/en/chapters/rfcs/version-naming.xml:1.3
--- peardoc/en/chapters/rfcs/version-naming.xml:1.2	Sun May  3 13:21:22 2009
+++ peardoc/en/chapters/rfcs/version-naming.xml	Sun May  3 16:56:43 2009
@@ -7,7 +7,7 @@
     <title>Version Naming</title>
   </info>
 
-  <para>This RFC has been voted on in PEPr as<link
+  <para>This RFC has been voted on in PEPr as <link
   xlink:href="&url.pear.pepr.proposal;65">proposal #65</link>.</para>
 
   <para>As discussed previously on pear-group, where a full consensus could

http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/rfcs/header-comments.xml?view=markup&rev=1.1
Index: peardoc/en/chapters/rfcs/header-comments.xml
+++ peardoc/en/chapters/rfcs/header-comments.xml
<?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0" xml:id="chapters.rfcs.header-comments"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:phd="http://www.php.net/ns/phd"
>
  <info>
    <title>Header comment blocks</title>

    <abstract>
      <para>The current "Header Comment Blocks" portion of the Coding
      Standards was basically copied from PHP sources without alteration.
      Those headers are often construed to indicate that the license summary
      for the PHP License and the PHP Group copyright must be included in each
      file, even if a different license and/or copyright are used.</para>

      <para>In addition, the header comments aren't parseable by
      phpDocumentor.</para>
    </abstract>

    <date>2005-02-02</date>
  </info>

  <para>This RFC has been voted on in PEPr as
   <link xlink:href="&url.pear.pepr.proposal;128">proposal #128</link>.
  </para>

  <section xml:id="chapters.rfcs.header-comments.base">
    <title>Base docblock</title>

    <para>All source code files in the PEAR repository shall contain a
    "page-level" docblock at the top of each file and a "class-level" docblock
    immediately above each class. Below are examples of such docblocks.</para>

    <programlisting role="php">&lt;?php

/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * PHP versions 4 and 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * 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 web, please
 * send a note to [email protected] so we can mail you a copy immediately.
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author &lt;[email protected]&gt;
 * @author     Another Author &lt;[email protected]&gt;
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id: header-comments.xml,v 1.1 2009/05/03 16:56:43 cweiske Exp $
 * @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
 */

// Place includes, constant defines and $_GLOBAL settings here.

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @category   CategoryName
 * @package    PackageName
 * @author     Original Author &lt;[email protected]&gt;
 * @author     Another Author &lt;[email protected]&gt;
 * @copyright  1997-2005 The PHP Group
 * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
 * @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 foo
{
}
?&gt;</programlisting>
  </section>

  <section xml:id="chapters.rfcs.header-comments.required">
    <title>Required tags</title>

    <section>
      <title>Short Descriptions</title>

      <para>Short descriptions must be provided for all docblocks. They should
      be a quick sentence, not the name of the item. Please read the
      <link linkend="standards.sample">Coding
      Standard's sample file</link> about how to write good descriptions.
      </para>
    </section>

    <section>
      <title>PHP Versions</title>

      <para>One of the following must go in the page-level docblock:</para>

      <itemizedlist>
        <listitem>
          <para>PHP version 4</para>
        </listitem>

        <listitem>
          <para>PHP version 5</para>
        </listitem>

        <listitem>
          <para>PHP versions 4 and 5</para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>@license</title>

      <para>There are several possible licenses. One of the following must be
      picked and placed in the page-level and class-level docblocks:</para>

      <itemizedlist>
        <listitem>
          <para><literal>@license http://www.apache.org/licenses/LICENSE-2.0
          Apache License 2.0</literal></para>
        </listitem>

        <listitem>
          <para><literal>@license
          http://www.freebsd.org/copyright/freebsd-license.html BSD License (2
          Clause)</literal></para>
        </listitem>

        <listitem>
          <para><literal>@license http://www.debian.org/misc/bsd.license BSD
          License (3 Clause)</literal></para>
        </listitem>

        <listitem>
          <para><literal>@license
          http://www.freebsd.org/copyright/license.html BSD License (4
          Clause)</literal></para>
        </listitem>

        <listitem>
          <para><literal>@license http://www.gnu.org/copyleft/lesser.html LGPL
          License 2.1</literal></para>
        </listitem>

        <listitem>
          <para><literal>@license http://www.php.net/license/3_0.txt PHP
          License 3.0</literal></para>
        </listitem>
      </itemizedlist>

      <para>For more information, see the PEAR Group's Licensing Announcement:
      http://pear.php.net/group/docs/20040402-la.php</para>
    </section>

    <section>
      <title>@link</title>

      <para>The following must be used in both the page-level and class-level
      docblocks. Of course, change "PackageName" to the name of your package.
      This ensures the generated documentation links back your package.</para>

      <para><literal>@link
      http://pear.php.net/package/PackageName</literal></para>
    </section>

    <section>
      <title>@author</title>

      <para>There's no hard rule to determine when a new code contributor
      should be added to the list of authors for a given source file. In
      general, their changes should fall into the "substantial" category
      (meaning somewhere around 10% to 20% of code changes). Exceptions could
      be made for rewriting functions or contributing new logic.</para>

      <para>Simple code reorganization or bug fixes would not justify the
      addition of a new individual to the list of authors.</para>
    </section>

    <section>
      <title>@since</title>

      <para>This tag is required when a file or class is added after the
      package's initial release. Do not use it in an initial release.</para>
    </section>

    <section>
      <title>@deprecated</title>

      <para>This tag is required when a file or class is no longer used but
      has been left in place for backwards compatibility.</para>
    </section>
  </section>

  <section xml:id="chapters.rfcs.header-comments.optional">
    <title>Optional tags</title>

    <section>
      <title>@copyright</title>

      <para>Feel free to apply whatever copyrights you desire. When formatting
      this tag, the year should be in four digit format and if a span of years
      is involved, use a hyphen between the earliest and latest year. The
      copyright holder can be you, a list of people, a company, the PHP Group,
      etc.</para>

      <para>Examples:</para>

      <itemizedlist>
        <listitem>
          <para><literal>@copyright 2003 John Doe and Jennifer
          Buck</literal></para>
        </listitem>

        <listitem>
          <para><literal>@copyright 2001-2004 John Doe</literal></para>
        </listitem>

        <listitem>
          <para><literal>@copyright 1997-2004 The PHP Group</literal></para>
        </listitem>

        <listitem>
          <para><literal>@copyright 2001-2004 XYZ Corporation</literal></para>
        </listitem>
      </itemizedlist>
    </section>

    <section>
      <title>License Summary</title>

      <para>If you are using the PHP License, use the summary text provided
      above. If another license is being used, please remove the PHP License
      summary. Feel free to substitute it with text appropriate to your
      license, though to keep things easy to locate, please preface the text
      with "<literal>LICENSE:</literal>".</para>
    </section>

    <section>
      <title>@version</title>

      <para>There were several comments about what to put in the @version
      tags. This proposal uses the CVS "<literal>Id</literal>" tag for the
      "page-level" docblock which covers the file, while the class-level
      docblocks will use <literal>@package_version@</literal>, which gets
      replaced with the release's version number by the PEAR installer.</para>

      <para>This seems the best compromise because <literal>$Id: header-comments.xml,v 1.1 2009/05/03 16:56:43 cweiske Exp $</literal>'s
      talk about files while the release version numbers talk about the
      classes. <literal>$Id: header-comments.xml,v 1.1 2009/05/03 16:56:43 cweiske Exp $</literal> is used rather than
      <literal>$Revision: 1.1 $</literal> or other shorter tags because it is the
      standard and provides all of the potentially desired information.</para>
    </section>

    <section>
      <title>@see</title>

      <para>Add a <literal>@see</literal> tag when you want to refer users to
      other sections of the package's documentation. If you have multiple
      items, separate them with commas rather than adding multiple
      <literal>@see</literal> tags.</para>
    </section>
  </section>

  <section xml:id="chapters.rfcs.header-comments.orderspacing">
    <title>Order and spacing</title>

    <para>To ease long term readability of PEAR source code, the text and tags
    must conform to the order and spacing provided in the example above. This
    standard is adopted from the JavaDoc standard.</para>
  </section>

  <section xml:id="chapters.rfcs.header-comments.packageversion">
    <title>@package_version@ Usage</title>

    <para>There are two ways to implement the @package_version@ replacements.
    The procedure depends on whether you write your own
    <filename>package.xml</filename> files or if you use the
     <link linkend="package.pear.pear-packagefilemanager">PackageFileManager</link>.
    </para>

    <para>For those authoring package.xml files directly, add a
    &lt;replace&gt; element for each file. The XML for such would look
    something like this:</para>

    <programlisting role="xml">&lt;file name="Class.php"&gt;
  &lt;replace from="@package_version@" to="version" type="package-info" /&gt;
&lt;/file&gt;</programlisting>

    <para>Maintainers using the PackageFileManager need to call
     <phd:pearapi phd:package="PEAR_PackageFileManager"
      phd:linkend="PEAR_PackageFileManager::addReplacement">addReplacement()</phd:pearapi>
     for each file:
    </para>

    <programlisting role="php">$pkg-&gt;addReplacement(
    'filename.php', 'package-info',
    '@package_version@', 'version'
);</programlisting>
  </section>

  <section xml:id="chapters.rfcs.header-comments.transition">
    <title>Transition policy</title>

    <section>
      <title>Existing Small Packages</title>

      <para>Existing packages that have only a few files are required to adopt
      these docblocks before the next release.</para>
    </section>

    <section>
      <title>Existing Large Packages</title>

      <para>Existing packages with many files are encouraged to adopt the new
      headers as soon as possible. When such packages come out with a new
      major version upgrade, these docblocks must be implemented
      therein.</para>
    </section>

    <section>
      <title>New Packages</title>

      <para>New packages and existing packages which have no releases yet must
      include these docblocks before their first release.</para>
    </section>
  </section>
</chapter>