-
Notifications
You must be signed in to change notification settings - Fork 1
Documenting your code
In order to supply API documentation to the end user and 3rd party developers it is important to fully document your code. Once complete we can then run phpDocumentor
This is a quick guide on how to format your docs in order to keep docs consistent across all extensions, for full usage instructions you should visit the phpDocumentor website
A page level docblock occurs at the beginning of a php file and it is used to describe the entire php file. Here follows the structure you should follow:
<?php
/**
* @version $Id$
* @category Ninjaextension
* @package Controller
* @copyright Copyright NinjaForge. All rights reserved.
* @license GNU GPLv2 <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html>
* @link http://ninjaforge.com
*/
defined('KOOWA') or die("Koowa isn't available, or file is accessed directly");
- @version - should be automatically filled in by your svn client
- @category - should be the name of your extension it should follow this naming convention Ninjaextension (ie: Ninjacontent, Ninjaboard)
- @package - should be the a description of the file, ie Controller, View, Model, Helper
- @copyright, @licence, @link - should always remain the same as above
You should document the class as follows, taking note that @category and @package should be the same as your page level block
/**
* A description of this class
*
* @category Ninjaextension
* @package Controller
*/
class ComNinjaextentionControllerDashboard extends ComNinjaControllerDashboard
{
/**
* Constructor
*
* @param object An optional KConfig object with configuration options
*/
public function __construct(KConfig $config)
{
When documenting methods the doc block should tell you what the method is, what it does, the parameters it excepts and finally what it returns
/**
* Edit action, saves over an existing item
*
* @param mixed Either a scalar, an associative array, an object or a KDatabaseRow
* @return KDatabaseRowset A rowset object containing the updated rows
*/
protected function _actionEdit($data)
{
the current template we are using is attached, please download it and follow then installation instructions, once youve done that come back here
running phpdoc is very easy simply open terminal and do the following
phpdoc -o HTML:frames/Extjs:default -d /directorytoproject -t /directorytooutput
just to explain what each part does
phpdoc //calles phpdocumentor
-0 HTML:frames/Extjs:default //tells it that we want to output in the Extjs template
-d /directorytoproject //tells it that we want it to do an entire directory, should be the path to your project directory
-t /directorytooutput //the target directory you want the docs to be placed
and thats it should be all done