Location: PHPKode > projects > PhpScribe Documentation Generator > templates/help.tpl
                 <TABLE cellSpacing=0 cellPadding=10 width=564>
                   <TBODY>
                   <TR>
                     <TD>
                     <p class='bodytext'>
                     These are the help topics of phpScribe.<br><br>
                     Here you'll be able to be familiar with the comment patterns
                     of the parser and to read some tips about the process of generating
                     the documentation files to your projects. Choose a topic below:
                     </p>
                     <a href='#comment_patterns' class='normalblue'>1. Comment Patterns</a><br><br>
                     &nbsp;&nbsp;&nbsp;<a href='#comment_delimiter' class='normalblue'>1.1. General Comment Delimiter</a><br><br>
                     &nbsp;&nbsp;&nbsp;<a href='#constant_comments' class='normalblue'>1.2. Constant Comments</a><br><br>
                     &nbsp;&nbsp;&nbsp;<a href='#classes_comments' class='normalblue'>1.3. Classes Comments</a><br><br>
                     &nbsp;&nbsp;&nbsp;<a href='#properties_comments' class='normalblue'>1.4. Class Properties Comments</a><br><br>
                     &nbsp;&nbsp;&nbsp;<a href='#methods_comments' class='normalblue'>1.5. Class Methods Comments</a><br><br>
                     &nbsp;&nbsp;&nbsp;<a href='#function_comments' class='normalblue'>1.6. Function Comments</a><br><br>
                     <a href='#documentation_generation' class='normalblue'>2. Documentation Generation</a><br><br>
                     </TD>
                   </TR>
                   <TR>
                     <TD CLASS='bodytext' COLSPAN='3' VALIGN='top'>

<a name='comment_patterns'></a>
<b>1. Comment Patterns</b><br><br>
To get your source codes documented by phpScribe, you'll have to follow some comment patterns which
can be understood by the parser. That pattern has to be applied when commenting classes and its properties,
constructor and methods and general project files and its functions.<br><br>
<a class='subnav' href='#top'>Back to the Top</a><br><br>
<a name='comment_delimiter'></a>

<b>1.1. General Comment Delimiter</b><br><br>
Use the character sequence <code>//!</code> to start and end comment lines in <i>classes</i>, <i>methods</i> and <i>
functions</i>. The class properties doesn't need comment delimiters.<br>
The lines between the delimiters must contain <code>//</code> in the first two positions, to
be skipped by PHP's parser. The multiline comment <code>/* */</code> won't be understood by phpScribe's parser (at least not yet...).<br><br>
<a class='subnav' href='#top'>Back to the Top</a><br><br>
<a name='constant_comments'></a>

<b>1.2. Constant Comments</b><br><br>
The constant declared in your source codes must have, above, beside or below the real declaration, a comment line with the following format:<br><br>

<pre style='font-size:12px'>
// @const MY_CONSTANT "some value" This constant defines a value
// @const MY_DB_HOST "localhost" Defines my database host
</pre>

This order must be respected:<br>
a) <code>// @const</code><br>
b) <code>MY_CONSTANT</code>: constant name<br>
c) <code>"some value"</code>: value of the constant. The double quotes are mandatory even if the value is not a string<br>
d) <code>This constant defines a value</code>: the description of the constant.<br><br>
<a class='subnav' href='#top'>Back to the Top</a><br><br>
<a name='classes_comments'></a>

<b>1.3. Classes Comments</b><br><br>
Follow the example below to write the comment lines to your project's classes:<br><br>

<pre style='font-size:12px'>
//!-----------------------------------------
// @class		myClass
// @desc		This class makes this and that
//		You can write the description in one or more lines...
// @package	myClassesPackage
// @extends	upClass
// @uses		classA
// @uses		classB
// @author	John R.
// @since		myProject v. 1.0.1
// @version	1.0.1
// @note		Use this class to build this and that
// @note		Add one or more notes per class, if necessary
// @static
//!-----------------------------------------
</pre>

The above words preceeded by '@' have the following meanings:<br><br>
<code>@class</code>: The class name.<br>
<code>@desc</code>: A brief description of the class purpose.<br>
<code>@package</code>: The name of the package in which the class is included.<br>
<code>@extends</code>: The name of the class extended by the current class (only once per class).<br>
<code>@uses</code>: If you instantiate 'classA' in 'myClass', then myClass 'uses' classA (provide one or more @uses lines).<br>
<code>@author</code>: The class author(s).<br>
<code>@since</code>: Use this tag to represent the software version in which the class was included.<br>
<code>@version</code>: Version of the class.<br>
<code>@note</code>: Some note or advice about the class (you can add one or more notes).<br>
<code>@static</code>: Add this tag if this is a static class<br>
P.S.: Only the tags @class and @desc are mandatory.<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The '-' characters are not necessary. We put them here for stetic reasons.<br><br>
<a class='subnav' href='#top'>Back to the Top</a><br><br>
<a name='properties_comments'></a>

<b>1.4. Class Properties Comments</b><br><br>
Each property must have, above, beside or below the real declaration, a comment line formatted like this:<br><br>

<pre style='font-size:12px'>
// @var myVar1 int                  "1" this var stores the value of...
// @var myVar2 string               "foo" this is a string var in my class
// @var myArray array               this is an array
// @var myObj AnotherClass object   this is an instance of AnotherClass
</pre>

This order must be respected:<br>
a) <code>// @var</code><br>
b) <code>myVar</code>: property name<br>
c) <code>int</code>: datatype of the property. it's optional.<br>
d) <code>"foo"</code>: initial value of the property. It's optional, but if present the double quotes are mandatory.<br>
e) <code>this var stores the value of...</code>: the description of the property.<br><br>
Between one and another element, it doesn't matter how many spaces or tabs are found. The system converts all tabs and spaces in only one space.<br><br>
<a class='subnav' href='#top'>Back to the Top</a><br><br>
<a name='methods_comments'></a>

<b>1.5. Class Methods Comments</b><br><br>
The methods of a class must respect the following pattern:<br><br>

<pre style='font-size:12px'>
//!-----------------------------------------
// @function	className::methodName
// @desc		This method makes this and that.
// @access	public
// @param		param1 int	"default value" first parameter
// @param		param2 string	second parameter
// @param		param3 Abc object	an object parameter
// @return	string Some value
// @see		className::methodRelated
// @author	John R.
// @since		0.0.1
// @version	1.2
// @note		Execute Foo::bar() before to get the correct results.
// @static
// @deprecated
//!-----------------------------------------
</pre>

The above words preceeded by '@' have the following meanings:<br><br>
<code>@function</code>: The class that contains the method and the method name, separated by <code>::</code><br>
<code>@desc</code>: Description of the method<br>
<code>@access</code>: The accepted values are 'public', 'private' and 'proteced'. This tag was created
just to get some compatibility with other languages as C++<br>
<code>@param</code>: Description of the <i>n<sup>th</sup></i> parameter, respecting the following order:
var name, datatype, default value (if exists, with double quotes) and description<br>
<code>@returns</code> or <code>@return</code>: specify the return type and the return value of the method.<br>
Examples: // @return void, // @return bool, // @return string Some string, // @return int The code from the database<br>
<code>@see</code>: Provide here the methods that are related to the current method if they deal with the same data,
if they execute similar functions, if they execute in a sequence or if they interchange data<br>
<code>@author</code>: The author of the method<br>
<code>@note</code>: Some advice to get the best results from the method. You can provide many '@note' lines.<br>
<code>@since</code>: The version of the software that carries this method for the first time.<br>
<code>@version</code>: Version of the function<br>
<code>@deprecated</code>: Use this tag to indicate that this method is deprecated and must be replaced in the user's code.<br>
<code>@static</code> Use this tag to indicate that this method is static<br>
<br>
P.S.:<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;In a class method documentation, <code>@function</code> and <code>@desc</code> tags are mandatory.<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;If a parameter has a default value, the double quotes are mandatory.<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;If the return type is missing, the word 'unknown' will be used<br><br>
<a class='subnav' href='#top'>Back to the Top</a><br><br>
<a name='function_comments'></a>

<b>1.6. Function Comments</b><br><br>
The functions located outside the project's classes must be documented like this:<br><br>

<pre style='font-size:12px'>
//!-----------------------------------------
// @function	&amp;functionName
// @desc		This function makes this and that.
// @param		&amp;param1 MyClass object	"NULL" first parameter
// @param		param2 resource		second parameter
// @return	MyClass object Some value
// @see		className::methodRelated
// @author	John R.
// @note		This function can be used to get the value of...
// @since		1.4b
// @version	1.2
// @deprecated
//!-----------------------------------------
</pre>

The above words preceeded by '@' have the following meanings:<br><br>
<code>@function</code>: The function name. The char '&' means a reference return<br>
<code>@desc</code>: Description of the function<br>
<code>@param</code>: Description of the <i>n<sup>th</sup></i> parameter, respecting the following order:
var name, datatype, default value (if exists, with double quotes) and description. The char '&' means <B>taking by reference</B> (don't confuse with passing by)<br>
<code>@returns</code> or <code>@return</code>: specify the return value of the function<br>
Examples: // @return void, // @return bool, // @return string Some string, // @return int The code from the database<br>
<code>@see</code>: Provide here the functions that are related to the current function if they deal with the same data,
if they execute similar functions, if they execute in a sequence or if they interchange data<br>
<code>@author</code>: The author of the function<br>
<code>@note</code>: Some advice to get the best results from the function. You can provide many '@note' lines.<br>
<code>@since</code>: The version of the software that carries this function for the first time.<br>
<code>@version</code>: Version of the function<br>
<code>@deprecated</code>: Use this word to indicate that this function is deprecated.<br>
<br>
P.S.:<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;In a function documentation, <code>@function</code> and <code>@desc</code> are mandatory.<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The tags @static and @package doesn't have effect in function comments<br><br>
<a class='subnav' href='#top'>Back to the Top</a><br><br>
<a name='documentation_generation'></a>

<b>2. Generation my Project's Documentation</b><br><br>
If you have your project correctly documented respecting phpScribe's pattern, and your
document generator is working well, it's almost all done! Just create a new project in the section
'My Projects' and then generate its documentation. Some of the documentation parameters are described here:<br><br>
<b>»</b> <i>Skin</i>: This documentation generation system have some color schemes stored that can be applied
to the HTML files. Choose the color collection you like more or the one that harmonize with
the project's purpose or theme.<br>
<b>»</b> <i>Parse Classes Only</i>: Choose yes to skip the elements that aren't classes, class methods or properties.<br>
<b>»</b> <i>Include Private Members</i>: Choose no to hide the private methods of the classes in the documentation.<br>
<b>»</b> <i>Generation Type</i>: Choose 'Store on the Server' to write the documentation in a folder of the Web Server where
your phpScribe copy is running. On the other hand, choose 'Download the Files' to generate a .zip file containing the
documentation of your project. Download it to save it in your machine or everywhere you want.<br><br>
<a class='subnav' href='#top'>Back to the Top</a><br><br>
                     </TD>
                    </TR>
                    </TBODY>
                   </TABLE>
Return current item: PhpScribe Documentation Generator