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 8-1. A function skeleton (func-name.xml) <?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.60 $ -->
<refentry id="function.func-name">
<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>
<varlistentry>
<term><parameter>thirdparameter</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="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. 4.3.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="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:"../../../../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. A reference.xml skeleton <?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.60 $ -->
<!-- Purpose: xx -->
<!-- Membership: xx -->
<!-- State: xx -->
<reference id="ref.extname">
<title>Extname &Functions;</title>
<titleabbrev>Extname</titleabbrev>
<partintro>
<section id="extname.intro">
&reftitle.intro;
<para>
</para>
</section>
<section id="extname.requirements">
&reftitle.required;
<para>
</para>
</section>
&reference.extname.configure;
&reference.extname.ini;
<section 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:"../../../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 8-3. A configure.xml skeleton <?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.60 $ -->
<section id="extname.installation">
&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:"../../../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-4. A constants.xml skeleton <?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.60 $ -->
<section id="extname.constants">
&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:"../../../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-5. A ini.xml skeleton <?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.60 $ -->
<section id="extname.configuration">
&reftitle.runtime;
&extension.runtime;
<para>
<table>
<title>Extname &ConfigureOptions;</title>
<tgroup cols="3">
<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 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:"../../../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
--> |
|