doc:skeletons:oo

OO extension skeleton

<methodname>classname::method</methodname> or 
<methodname>classname->method</methodname>
Note: Using <function> instead of <methodname> works too.
Note: <classname>classname</classname> does not link, but should soon.

File structure

Same as on http://doc.php.net/wiki/skeletons with the exception of reference.xml (and all the &reference.extname.reference; entities), if the extension does not define any regular functions, which is replaced by classname.xml where “classname” is the lowercase name of the class (one file per class).

classname.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: $ -->
<reference xml:id="class.classname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
 <title>The ClassName class</title>
 <titleabbrev>ClassName</titleabbrev>
 
 <partintro>
 
<!-- {{{ ClassName intro -->
  <section xml:id="classname.intro">
   &reftitle.intro;
   <para>
    Description of the class.
   </para>
  </section>
<!-- }}} -->
 
  <section xml:id="classname.synopsis">
   <title>Class synopsis</title>
 
<!-- {{{ Synopsis -->
   <classsynopsis>
    <ooclass><classname>ClassName</classname></ooclass>
 
<!-- {{{ Class synopsis -->
    <classsynopsisinfo>
     <ooclass>
      <classname>ClassName</classname>
     </ooclass>
 
<!-- If the class extends another one, use this -->
     <ooclass>
      <modifier>extends</modifier>
      <classname>BaseClassName</classname>
     </ooclass>
 
<!-- If the class implements an interface, or two, use this (one oointerface element per interface) -->
     <oointerface>
      <interfacename>InterfaceName</interfacename>
     </oointerface>
 
    </classsynopsisinfo>
<!-- }}} -->
 
    <classsynopsisinfo role="comment">Properties</classsynopsisinfo>
<!-- If the property is documented below (xml:id=classname.props) use this -->
    <fieldsynopsis>
     <modifier>public</modifier>
     <type>string</type>
     <varname linkend="classname.props.name">name</varname>
    </fieldsynopsis>
 
<!-- If the property is documented "as a method", use this -->
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:fieldsynopsis[1])" />
 
    <classsynopsisinfo role="comment">Methods</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
 
<!-- Again, if the class extends a class use this -->
    <classsynopsisinfo role="comment">Inherited methods</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.baseclassname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" />
   </classsynopsis>
<!-- }}} -->
 
  </section>
 
<!-- {{{ ClassName properties -->
  <section xml:id="classname.props">
   &reftitle.properties;
   <variablelist>
    <varlistentry xml:id="classname.props.name">
     <term><varname>name</varname></term>
     <listitem>
      <para>Prop description</para>
     </listitem>
    </varlistentry>
   </variablelist>
  </section>
<!-- }}} -->
 
 </partintro>
 
 &reference.extname.classname.entities;
 
</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
-->
classname/methodname.xml

The only difference here (compared to the usual function skeletons) is the xml:id attribute, the refname & methodname elements - and the possibility to document a property. Note: If this method/property has an alternate procedural mapping the procedural synopsis MUST be listed AFTER the method synopsis.

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision:$ -->
<refentry xml:id="classname.methodname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>ClassName::methodName</refname>
  <refpurpose>The methodName purpose</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
<!-- If its a normal method, use this -->
  <methodsynopsis>
   <!-- Example: All functions have this -->
   <type>thereturned type</type><methodname>ClassName::methodName</methodname>
   <!-- Example: Required parameter -->
   <methodparam><type>param1type</type><parameter>firstparameter</parameter></methodparam>
   <!-- Example: Optional parameter, also by reference -->
   <methodparam choice="opt"><type>int</type><parameter role="reference">secondparameter</parameter></methodparam>
   <!-- Example: If no methodparams exist (void), use this -->
   <void />
  </methodsynopsis>
<!-- If this is an property, use this -->
  <classsynopsis>
   <ooclass><classname>className</classname></ooclass>
   <fieldsynopsis><type>string</type><varname>name</varname></fieldsynopsis>
  </classsynopsis>
 
<!-- Note: If this method/property as an alternate procedural mapping then the method/property synopsis MUST be listed BEFORE the function synopsis -->
  <para>
   The method description goes here.
  </para>
 </refsect1>
 ....
</refentry>
doc/skeletons/oo.txt · Last modified: 2011/04/06 12:59 (external edit)