View Source

<ac:macro ac:name="toc"><ac:parameter ac:name="maxLevel">3</ac:parameter></ac:macro>

<h2>Overview</h2>

<p>The current Zend Framework documentation suffers from a number of issues, most<br />
prominently:</p>

<ul>
<li><strong>Missing information.</strong>
<ul>
<li>Much of the documentation does not cover all configuration options or available functionality, including available methods.</li>
<li>Most components do not include complete examples.</li>
<li>Extension points are often not discussed in complete detail. (Example given: most interfaces available are not detailed in the documentation.)</li>
</ul>
</li>
<li><strong>Unpredictable format.</strong>
<ul>
<li>Each component documents things in a slightly different way, making discovery of features difficult.</li>
<li>Some components will list options in one format, others in an entirely different way. This makes finding and understanding the options difficult.</li>
</ul>
</li>
</ul>


<p>Many ZF users have indicated that we should take an additional idea from the PHP manual, and use a standard layout for every component and/or class. This will provide several benefits:</p>

<ul>
<li>Component authors know exactly what documentation they must provide, and how to do so.</li>
<li>Users know exactly where to look for specific functionality of a component and/or class.</li>
<li>Such an approach lends itself well to consistency of URLs as well, further increasing predictablity.</li>
</ul>


<h2>Use DocBook5</h2>

<p>Zend Framework 2 will mark the first version of the framework where documentation is written using DocBook5. This will help simplify structure and syntax, and also work better with next generation tools such as PhD, REST-NG, etc.</p>

<h2>Theory of Operation</h2>

<p>First, all components will include sections on the following:</p>

<ul>
<li><strong>Overview</strong>, which will detail the problem the component addresses, as well as theory of operation.</li>
<li><strong>Quick Start</strong>, which will provide an overview and examples detailing the most common use case(s).</li>
<li><strong>Configuration Options</strong>, which will provide an overview of each configuration option available (if any), including accepted values.</li>
<li><strong>Available Methods</strong>, which will detail each available method, the arguments it accepts, and the return value.</li>
<li><strong>Examples</strong>, which will be a &quot;cookbook&quot; like chapter, showing additional use cases. This section will likely expand for each component over time to cover frequently asked questions.</li>
</ul>


<p>This proposal does not currently seek to address components with adapters, plugins, helpers, etc.; a later proposal will address structure for such components. </p>

<h3>Identifiers</h3>

<p>Identifiers will be named after the namespace and component; &quot;CamelCased&quot; names will be converted to &quot;lowercase-dash-separated&quot;.</p>

<h3>XML Structure</h3>

<p>The basic structure of a document will look as follows:</p>

<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<section id="zend.loader.class-map-autoloader">
<info><title>The ClassMapAutoloader</title></info>

<section id="zend.loader.class-map-autoloader.intro">
<info><title>Overview</title></info>
</section>

<section id="zend.loader.class-map-autoloader.quick-start">
<info><title>Quick Start</title></info>
</section>

<section id="zend.loader.class-map-autoloader.options">
<info><title>Configuration Options</title></info>

<variablelist>
<title>ClassMapAutoloader Options</title>

<varlistentry>
<term></term>

<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section id="zend.loader.class-map-autoloader.methods">
<info><title>Available Methods</title></info>

<variablelist>
<varlistentry id="zend.loader.class-map-autoloader.methods.method-name">
<term>
<methodsynopsis>
<methodname></methodname>
<methodparam>
<funcparams></funcparams>
</methodparam>
</methodsynopsis>
</term>

<listitem>
<para>
</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section id="zend.loader.class-map-autoloader.examples">
<info><title>Examples</title></info>

<example id="zend.loader.class-map-autoloader.examples.example-name">
<info><title></title></info>

<para></para>

<programlisting language="php"><![CDATA[
]]]]><![CDATA[></programlisting>
</example>
</section>
</section>
]]></ac:plain-text-body></ac:macro>

<p>Important items to note include:</p>

<ul>
<li>Configuration options will use a &lt;variablelist&gt; element with a &lt;varlistentry&gt; element per configuration option.</li>
<li>Methods will be detailed using a &lt;varlistentry&gt; per method. Parameters will be described using a &lt;funcparams&gt; element, containing simply a string with the elements:
<ac:macro ac:name="code"><ac:default-parameter>xml</ac:default-parameter><ac:plain-text-body><![CDATA[
<funcparams>Foo $foo, array $options = null</funcparams>
]]></ac:plain-text-body></ac:macro>
The arguments will be detailed within the &lt;listitem&gt; if they need explanation.</li>
</ul>


<p>We will also likely develop a tool to autogenerate the &quot;Methods&quot; section from the class files; this will speed up writing these sections, and provide a nice skeleton from which to work.</p>

<h2>Examples</h2>

<ul>
<li><a href="http://git.zendframework.com/?a=viewblob&amp;p=zf&amp;h=901fa6242cd52082092a7285bd8b10c910454ee8&amp;hb=df37795d665bcf10d3445327643f0c37e8e585a6&amp;f=documentation/manual/en/module_specs/Zend_Loader-ClassMapAutoloader.xml">ClassMapAutoloader example</a></li>
<li><a href="http://git.zendframework.com/?a=viewblob&amp;p=zf&amp;h=b59067eaad47fc836563fc063f402562b456412c&amp;hb=df37795d665bcf10d3445327643f0c37e8e585a6&amp;f=documentation/manual/en/module_specs/Zend_Loader-SplAutoloader.xml">SplAutloader example</a></li>
<li><a href="http://git.zendframework.com/?a=viewblob&amp;p=zf&amp;h=bf989f707453079187170fe3cd96ceb513a034ee&amp;hb=df37795d665bcf10d3445327643f0c37e8e585a6&amp;f=documentation/manual/en/module_specs/Zend_Loader-StandardAutoloader.xml">StandardAutoloader example</a></li>
<li><a href="http://git.zendframework.com/?a=viewblob&amp;p=zf&amp;h=c6cf2a699b4de521b86bddb71b33679a24f44084&amp;hb=df37795d665bcf10d3445327643f0c37e8e585a6&amp;f=documentation/manual/en/module_specs/Zend_Loader-AutoloaderFactory.xml">AutoloaderFactory example</a></li>
<li><a href="http://git.zendframework.com/?a=viewblob&amp;p=zf&amp;h=4d3ad731c917f6d49647e22b69e5d0805798b080&amp;hb=df37795d665bcf10d3445327643f0c37e8e585a6&amp;f=documentation/manual/en/module_specs/Zend_Loader-Classmap_Generator.xml">classmap_generator.php example</a></li>
</ul>