Chapter 8. Documentation Skeletons

Below are some "skeletons" to copy and paste from when adding documentation.

Example 8-1. Function reference file in lang/reference/EXTNAME/functions

<reference>
  <title></title>
  <titleabbrev></titleabbrev>

 </reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

Example 8-2. Function reference entry

<refentry id="function.">
   <refnamediv>
    <refname></refname>
    <refpurpose></refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <methodsynopsis>
      <type>RETURNTYPE</type> <methodname>FUNCTIONNAME</methodname>
      <methodparam><type>ARGTYPE1</type> <parameter>ARGNAME1</parameter></methodparam>
      <methodparam><type>ARGTYPE2</type> <parameter>ARGNAME2</parameter></methodparam>
      <methodparam choice='opt'><type>ARGTYPE3</type> <parameter>ARGNAME3</parameter></methodparam>
      <!-- use <void /> if you have no parameters at all -->
    </methodsynopsis>
    <simpara>
     A simple paragraph that can not contain anything that requires
     fancy layout.
    </simpara>
    <para>
     A normal paragraph that can contain lots of stuff.  For example
     <example>
      <title>Code examples</title>
      <programlisting role="php">
// Use CDATA here, see the bottom of this page

/* Use a role="php" only for PHP codes. See <screen>
 * and other DocBook elements to express other
 * types of listings. Use other role attributes for
 * other type of programlistings, like: sql, httpd, ini,
 * shell or http, as dictated by the example type.
 */

/* Do all indentation with spaces, not tabs, just to be sure.
 * Don't try pushing the code to the right by adding spaces in
 * front, this is the style sheet's job.
 */
 
// a function example
function some_code($foo)
{
    // use four spaces of indentation
}

// an example of bracket usage and spacing, always use
// brackets, even when they are physically not needed
if (some_code($foo) == "foo") {
    echo "foo";
} elseif (some_code($foo) == "bar") {
    echo "bar";
} else {
    echo "No foo, no bar";
}

// Include end of CDATA, if you started with CDATA, see below
      </programlisting>
     </example>

     The text in a paragraph may continue after the example as well.
     Here is how to make lists:

     <itemizedlist>
      <listitem>
       <simpara>
        List items must contain a container element such as
        simpara or para (there are plenty of others too, see the
        DocBook reference for the listitem element).
       </simpara>
      </listitem>

      <listitem>
       <simpara>
        List items must contain simple paragraphs or paragraphs.
       </simpara>
      </listitem>
     </itemizedlist>
     
     <itemizedlist>
      <listitem>
       <para>
        If you plan on making sub-lists, you must use para 
        <orderedlist>
         <listitem><simpara> first list item</simpara></listitem>
         <listitem><simpara> second list item</simpara></listitem>
        </orderedlist>
        You can also continue an ordered list you just left off
        <orderedlist>
         <listitem><simpara> third list item</simpara></listitem>
         <listitem><simpara> fourth list item</simpara></listitem>
        </orderedlist>
       </para>
      </listitem>
     </itemizedlist>

    </para>
    <simpara>
     The documentation for a function should be wrapped up with
     a "See also" list like this:
    </simpara>
    <simpara>
     See also <function>stripslashes</function> and
     <function>quotemeta</function>.
    </simpara>
   </refsect1>
  </refentry>

For technical reasons, the CDATA start tag: <![CDATA[ and the CDATA end tag: ]]> is not included in the listing above, just the place of them are marked. Use these tags to be able to write clearer example codes.

For parts we have no skeleton here, please look at existing files in the phpdoc CVS module. If you are not sure a specific file is good for a start, please ask on the phpdoc mailing list. If you have any suggestions for more skeletons do not hesitate.