Differences

This shows you the differences between two versions of the page.

dev:phpdoc_convention [2006/01/19 06:42]
editor
dev:phpdoc_convention [2009/07/06 20:36] (current)
Line 1: Line 1:
 +====== 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
 +<code>
 +/*
 + * This is NOT a docblock
 + *
 + */
 +</code>
 +    * THIS IS A DOCBLOCK
 +<code>
 +/**
 + * This is a docblock
 + * more stuff
 + */
 +</code>
 +
 +==== More on docblock ====
 +  * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock | you can use HTML tags inside docblock.]]
 +    * <b> -- emphasize/bold text
 +    * <nowiki><code></nowiki> -- 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 =====
 +<code>
 +/* $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)
 + */
 +</code>
 +===== Function Headers =====
 +<code>
 +/**
 + * 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
 + */
 +</code>
 +   Example
 +<code>
 +/**
 + * 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;
 +}
 +</code>
 +
 +===== Important Tags =====
 +   * NOTE: not strictly tho
 +==== Header Block ====
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.author.pkg.html | @author ]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.copyright.pkg.html | @copyright ]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.license.pkg.html | @license ]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.package.pkg.html | @package ]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.subpackage.pkg.html | @subpackage ]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.tutorial.pkg.html | @tutorial ]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.version.pkg.html | @version ]]
 +==== Rest ====
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.link.pkg.html | @link]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.since.pkg.html | @since]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.global.pkg.html | @global]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.var.pkg.html | @var]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.param.pkg.html | @param]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.access.pkg.html | @access]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.return .pkg.html | @return ]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.todo.pkg.html | @todo]]
 +   * [[http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.deprecated.pkg.html | @deprecated]]
 +
 +===== 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 ====
 +   * You need to write in DocBook Style, [[http://www.docbook.org/tdg/en/html/ | read the manual]]
 +==== Okay, a quick guide ====
 +   * start, treat {@id <id>} like html anchors <a name="some_section">
 +<code>
 +<refentry id="{@id}">
 +</code>
 +   * Outline of the document as follows
 +     * Title section
 +     * Synopsis, can include the author, copyright, etc
 +     * Actual Sections
 +        * Title
 +        * Paragraphs
 +        * code samples , etc
 +<code>
 +<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>
 +</code>
 +==== 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
 +<code>
 +[Linked Tutorials]
 +ws_soap_hello_world
 +ws_xmp_rpc_hello_world
 +</code>

Navigation
  • Navigate