beingsane
5/13/2014 - 3:01 PM

gistfile1.md

Documentation Guide

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1. Introduction

Documentation is important because you are always working as a team, even if that team is only you and your future self. This guide addresses the minimum requirements for API documentation (DocBlocks) and style guides for inline commenting.

2. API Documentation (DocBlocks)

Overview

DocBlocks MUST start with /**.

Intermediate lines within a DocBlock must begin with * (first character is a real space).

DocBlocks MUST end with */ (first character is a real space).

File Docblock

Each PHP file MUST include a file Docblock at the head of the file, on the next line after the opening <?php tag.

A @license tag MUST be provided.

A @copyright tag MUST be provided.

Class Docblock

Each class MUST include a Docblock immediately before the class definition statement.

A @since tag SHOULD be provided.

Class Property/Constant Docblock

Each class property MUST include a DocBlock immediately before the property or constant definition statement.

A @var tag MUST be provided.

A @since tag SHOULD be provided.

Function or Class Method Docblock

Each function or class method MUST include a Docblock immediately before the function/method definition statement.

A @param tag MUST be provided for each argument in the function/method.

A @return tag MUST be provided.

A @throws tag MUST be provided if the function/method throws an exception.

A @since tag SHOULD be provided.

3. Inline Documentation

Ideally, code should be written to be read without the need for additional inline comments. However, inevitabilty they are necessary.

When commenting inline, C style comments (/* */) or standard C++ comments (//) MUST be used.

Perl/shell style comments (#) MUST NOT be used.