1. Comment Patterns
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.
Back to the Top
1.1. General Comment Delimiter
Use the character sequence //! to start and end comment lines in classes, methods and
functions. The class properties doesn't need comment delimiters.
The lines between the delimiters must contain // in the first two positions, to
be skipped by PHP's parser. The multiline comment /* */ won't be understood by phpScribe's parser (at least not yet...).
Back to the Top
1.2. Constant Comments
The constant declared in your source codes must have, above, beside or below the real declaration, a comment line with the following format:
// @const MY_CONSTANT "some value" This constant defines a value
// @const MY_DB_HOST "localhost" Defines my database host
This order must be respected:
a) // @const
b) MY_CONSTANT: constant name
c) "some value": value of the constant. The double quotes are mandatory even if the value is not a string
d) This constant defines a value: the description of the constant.
Back to the Top
1.3. Classes Comments
Follow the example below to write the comment lines to your project's classes:
//!-----------------------------------------
// @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
//!-----------------------------------------
The above words preceeded by '@' have the following meanings:
@class: The class name.
@desc: A brief description of the class purpose.
@package: The name of the package in which the class is included.
@extends: The name of the class extended by the current class (only once per class).
@uses: If you instantiate 'classA' in 'myClass', then myClass 'uses' classA (provide one or more @uses lines).
@author: The class author(s).
@since: Use this tag to represent the software version in which the class was included.
@version: Version of the class.
@note: Some note or advice about the class (you can add one or more notes).
@static: Add this tag if this is a static class
P.S.: Only the tags @class and @desc are mandatory.
The '-' characters are not necessary. We put them here for stetic reasons.
Back to the Top
1.4. Class Properties Comments
Each property must have, above, beside or below the real declaration, a comment line formatted like this:
// @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
This order must be respected:
a) // @var
b) myVar: property name
c) int: datatype of the property. it's optional.
d) "foo": initial value of the property. It's optional, but if present the double quotes are mandatory.
e) this var stores the value of...: the description of the property.
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.
Back to the Top
1.5. Class Methods Comments
The methods of a class must respect the following pattern:
//!-----------------------------------------
// @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
//!-----------------------------------------
The above words preceeded by '@' have the following meanings:
@function: The class that contains the method and the method name, separated by ::
@desc: Description of the method
@access: The accepted values are 'public', 'private' and 'proteced'. This tag was created
just to get some compatibility with other languages as C++
@param: Description of the nth parameter, respecting the following order:
var name, datatype, default value (if exists, with double quotes) and description
@returns or @return: specify the return type and the return value of the method.
Examples: // @return void, // @return bool, // @return string Some string, // @return int The code from the database
@see: 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
@author: The author of the method
@note: Some advice to get the best results from the method. You can provide many '@note' lines.
@since: The version of the software that carries this method for the first time.
@version: Version of the function
@deprecated: Use this tag to indicate that this method is deprecated and must be replaced in the user's code.
@static Use this tag to indicate that this method is static
P.S.:
In a class method documentation, @function and @desc tags are mandatory.
If a parameter has a default value, the double quotes are mandatory.
If the return type is missing, the word 'unknown' will be used
Back to the Top
1.6. Function Comments
The functions located outside the project's classes must be documented like this:
//!-----------------------------------------
// @function &functionName
// @desc This function makes this and that.
// @param ¶m1 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
//!-----------------------------------------
The above words preceeded by '@' have the following meanings:
@function: The function name. The char '&' means a reference return
@desc: Description of the function
@param: Description of the nth parameter, respecting the following order:
var name, datatype, default value (if exists, with double quotes) and description. The char '&' means taking by reference (don't confuse with passing by)
@returns or @return: specify the return value of the function
Examples: // @return void, // @return bool, // @return string Some string, // @return int The code from the database
@see: 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
@author: The author of the function
@note: Some advice to get the best results from the function. You can provide many '@note' lines.
@since: The version of the software that carries this function for the first time.
@version: Version of the function
@deprecated: Use this word to indicate that this function is deprecated.
P.S.:
In a function documentation, @function and @desc are mandatory.
The tags @static and @package doesn't have effect in function comments
Back to the Top
2. Generation my Project's Documentation
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:
» Skin: 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.
» Parse Classes Only: Choose yes to skip the elements that aren't classes, class methods or properties.
» Include Private Members: Choose no to hide the private methods of the classes in the documentation.
» Generation Type: 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.
Back to the Top
|
