Header Comment Blocks

All source code files in the Mambo repository shall contain a "page-level" docblock at the top of each file and a "class-level" docblock immediately above each class. Below are examples of such docblocks.

<?php/**
* @package Mambo
* @author Mambo Foundation Inc see README.php
* @copyright Mambo Foundation Inc.
* See COPYRIGHT.php for copyright notices and details.
* @license GNU/GPL Version 2, see LICENSE.php
* Mambo is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; version 2 of the License.
*/

NOTE: The docblock above is a Mambo requirement.

Examples of docblocks to be included immediately above each class:

/*
* Place includes, constant defines and $_GLOBAL settings here.
* Make sure they have appropriate docblocks to avoid phpDocumentor
* construing they are documented by the page-level docblock.
*/

<?php
/**
* Short description for class
*
* Long description for class (if any)...
*
* @category CategoryName
* @package PackageName
* @author Original Author author@example.com
* @author Another Author another@example.com
* @copyright 1997-2005 The PHP Group
* @license http://www.php.net/license/3_0.txt PHP License 3.0
* @version Release: @package_version@
* @link http://pear.php.net/package/PackageName
* @see NetOther, Net_Sample::Net_Sample()
* @since Class available since Release 1.2.0
* @deprecated Class deprecated in Release 2.0.0
*/

class foo {

}
?>

Required Tags That Have Variable Content

Short Descriptions:
Short descriptions must be provided for all docblocks. They should be a quick sentence, not the name of the item.

@since
This tag is required when a file or class is added after the package's initial release. Do not use it in an initial release.

@deprecated
This tag is required when a file or class is no longer used but has been left in place for backwards compatibility.
Mambo's source code is read by thousands of people, from users to 3PD's, to future developers within the project. Therefore, it is important to make life easier for everyone by formatting the code and docblocks in standardized ways. People can then quickly find the information they are looking for because it is in the expected location. Your cooperation is appreciated.
Recommendation for 3PD's
Files not in the core Mambo repository should have a similar block stating the copyright, the license, and the authors. All files should include the modeline comments to encourage consistency.

Next: Example URL's