• This is a quick guide to get you started on php-doc, however we strongly recommend you to read the php-doc manual for more information {http://manual.phpdoc.org/}

• phpdoc parsers anything inside a docblock
• NOTE: following is NOT a docblock

/*
 * This is NOT a docblock
 * 
 */

• THIS IS A DOCBLOCK

/**
 * This is a docblock
 * more stuff
 */

• you can use HTML tags inside docblock.
  • <b> – emphasize/bold text
  • <code> – Use this to surround php code, some converters will highlight it
  • <br> – hard line break, may be ignored by some converters
  • <i> – italicize/mark as important
  • <kbd> – denote keyboard input/screen display
  • <li> – list item
  • <ol> – ordered list
  • <p> – If used to enclose all paragraphs, otherwise it will be considered text
  • <pre> – Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)
  • <samp> – denote sample or examples (non-php)
  • <ul> – unordered list
  • <var> – denote a variable name

/* $Id: lib_form.inc,v 1.1 2006/01/19 05:17:29 babytux Exp babytux $ */
/**
 *
 * Sahana HTML form library
 *
 * PHP version 4 and 5
 *
 * LICENSE: This source file is subject to LGPL license
 * that is available through the world-wide-web at the following URI:
 * http://www.gnu.org/copyleft/lesser.html
 *
 * @author     Chamindra de Silva <chamindra@opensource.lk>
 * @copyright  Lanka Software Foundation - http://www.opensource.lk
 * @package    library
 * @subpackage presentation
 * @tutorial   lib_form.pkg
 * @license    http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License (LGPL)
 */

/**
 * Short description of the function 
 * 
 * Long description (if needed may include code samples)
 * 
 * @param <type> <name of the variable>
 * e.g
 * @param string $name
 * @param bool $registered
 * @access <public or private>
 * e.g
 * access public
 * @return <type>
 * e.g
 * @return void
 */

 Example

/**
 * Cleans the given value to avoid SQL Injections 
 * 
 * Different databases uses different escape charaters, e.g mysql, postgres uses \ sqlite uses '
 * SQL Injection is done by supplying the escape character followed by the SQL to inject, in order to 
 * prevent this you need to escape the escape charater as well. Using this function you will NOT have to 
 * worry about different escape sequences used in different databases
 *
 * @param string $str 
 * @access public
 * @return string
 */
function shn_db_clean($str)
{
    global $global;
    $str = trim($str);
    $str = $global['db']->qstr($str,get_magic_quotes_gpc());
    return $str;
}

• NOTE: not strictly tho

• @author
• @copyright
• @license
• @package
• @subpackage
• @tutorial
• @version

• @link
• @since
• @global
• @var
• @param
• @access
• @return
• @todo
• @deprecated

• Package level - Apply to the whole package (.pkg)
• Class level - Apply to the class (.cls)
• Procedure level - Apply to the function (.proc)

• sahana-phase2/tutorials/<package name>/<subpackage name>/<tutorial file>

• You need to write in DocBook Style, read the manual

• start, treat {@id <id>} like html anchors <a name=“some_section”>

<refentry id="{@id}">

• Outline of the document as follows
  • Title section
  • Synopsis, can include the author, copyright, etc
  • Actual Sections
    • Title
    • Paragraphs
    • code samples , etc

<refentry id="{@id}">
    
    <refnamediv>
        <refname>WS - Hello World</refname>
        <refpurpose>Description of Hello World WebService</refpurpose>
    </refnamediv>

    <refsynopsisdiv>
        <refsynopsisdivinfo>
            <author> Foobar </author>
            <copyright>Copyright 2006, Foobar</copyright>
        </refsynopsisdivinfo>
    </refsynopsisdiv>

    <refsect1 id="{@id sec_xml_rpc}">
        <title>Hello World with XML-RPC</title>
        <para>Bla bla bla</para>
        <para>
            <programlisting role="php"><![CDATA[<?php $bla = 'hello'; ?>]]> 
            </programlisting>
        </para>
        
        <refsect2 id="{@id sec_soap}">
            <title>Hello World with SOAP</title>
            <para>Bla bla bla</para>
            <para>
                <programlisting role="php"><![CDATA[<?php $bla = 'hello'; ?>]]>
                </programlisting>
            </para>
        </refsect2>

    </refsect1>

</refentry>

• it look for the relative path, so if you are in the package and subpackage just type
  • @tutorial <tutorial file>
• Otherwise
  • @tutorial package/subpackage/<tutorial file>

• create an ini file with the <tutorial file>.ini

[Linked Tutorials]
ws_soap_hello_world
ws_xmp_rpc_hello_world