IMPORTANT

  • 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/}

Quick Guide

Docblock

  • 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
 */

More on 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

Header

/* $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)
 */

Function Headers

/**
 * 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;
}

Important Tags

  • NOTE: not strictly tho

Header Block

Rest

Writing Tutorials and linking them

Types of tutorials and file extension convention

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

Where to keep them

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

How to write

Okay, a quick guide

  • 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>

Linking using @tutorial

  • 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>

Linking Many Totorials

  • create an ini file with the <tutorial file>.ini
[Linked Tutorials]
ws_soap_hello_world
ws_xmp_rpc_hello_world

Navigation
  • Navigate