API Documentation site link:  http://qcu.be/doc/api/hierarchy.html

News

03/12/09 - Standards and Practices have been added.

Documentation Standards and Practices

QCubed is a community effort and the documentation portion of that is no different. While there are efforts by core contributors to improve and enhance the api documentation, any community help is always welcomed and appreciated. After all, QCubed is a pretty significant piece of software and we can't be experts on it all. Maybe there is some function that you know really well that is not fully documented yet. Or maybe you just want to help in the effort. Well, if that is the case, please do not hesitate to offer a solution to that problem. And here is how you do it.

First up is the documentation standard. For QCubed, we use the docblock. If you are familiar with phpDocumentor, you will recognize this term. If not, no worries. Here is how you will use the docblock in Qcubed and the tags you should use: 

/**
 * Class or method short description here.  Try to keep this to one or two lines
 *
 * The longer description will go here.  This description can be as long as necessary to get the meaning across
 *
 * @example ClassExample.php  to use an externally located example file
 * <code>
 *  code here for an internal example
 * </code>
 * 
 * @see A function or class related to this one.  Perhaps called by or call from within
 * @param param_type the description of the parameter
 * @return what the return value should be
 * @package a way to group classes and function.  For instance, there is an Action package that all action classes belong to. 
*/

There are actually only a few things in the docblock above that are required. First is the format. Docblocks must start with /** and must end with */. Also required for QCubed is the short description.

And that's it. Everything else is optional. There may not be a need for an example. Or the example might be short enough to include inline instead of in a file. In that case, you would use <code> instead of @example. You may not know what package this should belong to. Skip it. There is a default package that will apply. The only other thing we require is that you use correct English and avoid sentence fragments in the long description.

Here is an example: [Docblock usage]

Docblocks are used for files, classes and variables. When creating documentation for a file, the first docblock should ALWAYS be the file docblock. This does not have to be intensive; just a short description of what the file contains is fine. If the file contains a class, the next docblock is the class docblock. If you use a package tag, please ensure the package is the same for both file and class.

To review the proper usage of the above tags, please see the documentation of phpDocumentor at  phpDocumentor Manual

Now for the steps you should take to contribute.

  1. Check out the latest release from SVN.
  2. Start adding documentation where you desire.
  3. Once you are finished, create a patch for your changes.
  4. Create a ticket in TRAC with a short description of what you documented and attach the patch.
    1. (optional) If you have an example file, attach that file to the ticket as well.
  5. Someone will review the patch, making any necessary changes, contact you if needed, and will apply or reject the patch.

If you have an idea or corrections, please add a comment to the ApiWorkGroup page.