coding_standard:documentation [Ofuz

Coding Standard for Source Documentation

Each files needs a header comment with the following:

// Copyright 2010 SQLFusion LLC   info@sqlfusion.com
// All rights reserved

Then a second comment describing the scripts. All comments needs to follow the phpDoc / JavaDoc syntax. Start with : /** and ends with */ Must contain a phrase with a title and then the description. The @package is required and must contain the package name.

Example:

<?php
// Copyright 2010 SQLFusion LLC  info@sqlfusion.com
// All rights reserved
/**
 * Display Class
 *
 * It manage parameters from an internal array
 * and built a full url with the getUrl method.
 *
 * @package OfuzCore
 * @author Philippe Lewicki <phil@sqlfusion.com>
 * @license GNU Affero General Public License
 * @version 3.3.0
 * @date 2010-09-18
 */
?>

Comments within structural code should be avoid. The mixte of // comments with procedural code is not allowed. Explanation about the code should be written in plain text english on the top of the Page, Class, Function, Event or section. The comments will generate the documentation, so it should describe the code without the need to see it. Comments can be long and descriptive even with examples.

Possible @code

  @abstract
  @access access-type
  @author name-text
  @deprecated deprecated-text
  @final
  {@link package.class#member label}
  {@linkplain package.class#member label}
  @package package-name
  @param parameter-type parameter-name description
  @return return-type description
  @see packahge.class#member
  @since since-text
  @static
  @var var-type
  @version version-text

  Some Javadoc tags are not relevant to PHP and so are ignored, others
  are added or slightly changed due to PHPs loose typing:

  @abstract is a new tag defining a class or method as abstract.
  @access is a new tag and is valid within field and method doc comments.
          The first word after the tag should denote the access type of
          the field or method.
  @final is a new tag defining a class or method as final.
  @package is a new tag that places an item into a specific package and
          is valid within any doc comment of a top level item.
  @param has a parameter-type value added as the first word after the
          tag. This value should denote the data type of the parameter.
  @return has a return-type value added as the first word after the tag.
          This value should denote the methods or functions return data
          type.
  @static is a new tag defining a class, method or member variable as
          static.