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

Quick Guide


  • phpdoc parsers anything inside a docblock
  • NOTE: following is NOT a docblock
 * This is NOT 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
/* $Id:,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:
 * @author     Chamindra de Silva <>
 * @copyright  Lanka Software Foundation -
 * @package    library
 * @subpackage presentation
 * @tutorial   lib_form.pkg
 * @license 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
 * 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


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}">
        <refname>WS - Hello World</refname>
        <refpurpose>Description of Hello World WebService</refpurpose>

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

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



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]

QR Code
QR Code dev:phpdoc_convention (generated for current page)