Todo  Arabic Brazilian Portuguese Bulgarian Chinese (Simplified) Chinese (Hong Kong Cantonese) Chinese (Traditional) Czech Danish Dutch Finnish French German Greek Hebrew Hungarian Italian Japanese Korean Norwegian Persian Polish Portuguese Romanian Russian Serbian Slovak Slovenian Spanish Swedish Turkish English
Working with the PHP Documentation

Documentation Skeletons

Below are some "skeletons" to copy and paste from when adding documentation. All of these files should end with a line ending ("\n"). If a section does not exist (like a ChangeLog), simply don't include that refsect1 inside the documentation.

Note:

The documentation skeletons below are new, from around August of 2004.

Example #1 A function skeleton (func-name.xml)

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.func-name" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>func_name</refname>
  <refpurpose>The func_name purpose</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <!-- Example: All functions have this -->
   <type>thereturned type</type><methodname>func_name</methodname>
   <!-- Example: Required parameter -->
   <methodparam><type>int</type><parameter>firstparameter</parameter></methodparam>
   <!-- Example: Optional parameter -->
   <methodparam choice="opt"><type>string</type><parameter>secondparameter</parameter></methodparam>
   <!-- Example: Passed by reference -->
   <methodparam><type>bool</type><parameter role="reference">thirdparameter</parameter></methodparam>
   <!-- Example: If no methodparams exist (void), use this -->
   <void />
  </methodsynopsis>
  <para>
   The functions description goes here.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>firstparameter</parameter></term>
     <listitem>
      <para>
       Its description
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>secondparameter</parameter></term>
     <listitem>
      <para>
       Its description
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   What this function returns, first on success, then failure.  If simply
   true on success and false on failure, just use &return.success; here.
  </para>
 </refsect1>
 
 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   When does this function issue E_* level errors, or throw exceptions?
  </para>
 </refsect1>

 <refsect1 role="unicode">
  &reftitle.unicode;
  <para>
   Unicode information (introduced in PHP 6) goes here.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>Write the PHP version here (Ex. PHP 5.2.0)</entry>
       <entry>
        Describe the change
       </entry>
      </row>
      <row>
       <entry>...</entry>
       <entry>
        ...
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>functionname</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
if ($anexample === true) {
    echo 'Use the PEAR Coding standards';
}
if ($thereisoutput === 'and it is multiple lines') {
    echo 'Use a screen like we did below';
}
?>
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
Use the PEAR Coding standards
Use a screen like we did below
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <para>
   Any notes that don't fit anywhere else should go here.
   90% of the time, notes, warnings or cautions are better placed in the
   parameters section. Consider that before using this section!
  </para>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>somefunc</function></member>
    <member><function>another_func</function></member>
    <member>The <link linkend="something">something appendix</link></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>

<!-- 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:"~/.phpdoc/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 #2 A reference.xml skeleton

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- Purpose: xx -->
<!-- Membership: xx -->
<!-- State: xx -->
<reference xml:id="ref.extname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Extname &Functions;</title>
 <titleabbrev>Extname</titleabbrev>

 <partintro>
  <section xml:id="extname.intro">
   &reftitle.intro;
   <para>
     
   </para>
  </section>

  <section xml:id="extname.requirements">
   &reftitle.required;
   <para>
     
   </para>
  </section>

  &reference.extname.configure;
  &reference.extname.ini;

  <section xml:id="extname.resources">
   &reftitle.resources;
   &no.resource;
  </section>

  &reference.extname.constants;
 </partintro>

 &reference.extname.functions;

</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:"~/.phpdoc/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
-->

There are several PECL related entities inside of language-snippets.ent. Be sure to include information on where Windows users can find the DLL.

Example #3 A configure.xml skeleton

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<section xml:id="extname.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.install;
 <para>
  To enable extname support, configure PHP with 
  <option role="configure">theconfigoption</option>
 </para>
 <para>
  Windows users ...
 </para>
</section>

<!-- 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:"~/.phpdoc/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 #4 A constants.xml skeleton

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<section xml:id="extname.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.constants;
 &extension.constants;
 <para>
  <variablelist>
   <varlistentry>
    <term>
     <constant>CONSTANT_NAME</constant> 
     (<type>itstype</type>)
    </term>
    <listitem>
     <simpara>
     
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>
</section>

<!-- 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:"~/.phpdoc/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 #5 A ini.xml skeleton

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<section xml:id="extname.configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.runtime;
 &extension.runtime;
 <para>
  <table>
   <title>Extname &ConfigureOptions;</title>
   <tgroup cols="4">
    <thead>
     <row>
      <entry>&Name;</entry>
      <entry>&Default;</entry>
      <entry>&Changeable;</entry>
      <entry>Changelog</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>theini_option</entry>
      <entry>itsvalue</entry>
      <entry>its PHP_INI_* value</entry>
      <entry>leave this blank. it will be filled automatically</entry>
     </row>
    </tbody>
   </tgroup>
  </table>

  &php_ini_constants;
 </para>
 
 &ini.descriptions.title;
 
 <para>
  <variablelist>
   <varlistentry xml:id="ini.extname.theini-option">
    <term>
     <parameter>theini_option</parameter>
     <type>thetype</type>
    </term>
    <listitem>
     <para>
     
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </para>
</section>

<!-- 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:"~/.phpdoc/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
-->

Working with the PHP Documentation