07_Api documentation guidelines

1 phpDocs

The Bonfire API uses the phpDoc 2.0 system to generate the API documentation automatically. Please consult the documentation for help with the markup.

NOTE: Prior to 0.6, all version were using the Natural Docs system but were changed to allow better IDE helpers and calltips to be generated.

2 Wording

Write simple, declarative sentences. Brevity is a plus. Get to the point.

Write in the present tense: 'Returns an array that…', rather than "Returned an array.." or "Will return an array…".

Start comments in the uppercase and follow regular punctuation rules.

Documentation has to be concise but comprehensive. Explore and document edge cases.

3 English

Please use American English (color, center, modularize, etc). See a list of American and British English spelling differences here.

4 The DocBlock

The NaturalDocs docblock style is different than what many PHP developers may be used to. It is designed to be human-readable, and to create highly-readable documentation.

It should start with a definition of the class/function/etc. For methods and functions, include the parenthesis but not the parameters:

/*
	Method: render_view()
*/

This should be followed by a short description of what the method does. It might include when or why you would want to use it, but remember to be concise.

Next is a list of the Parameters that the method accepts, if applicable. Parameters should be on their own line, with the name and definition separated by a dash. The columns should be vertically aligned.

/*
	Parameters: 
		$view	- A string with the name of the view to render.
		$return	- If TRUE, will return the contents of the rendered view.
				  If FALSE, will echo the view to the screen.
*/

Only include the Returns: parameter if the method returns anything other than void, null or some other empty response.

/*
	Returns:
		Either a string with the contents of the rendered view, or FALSE.
*/

Only include Access if something other than public.

/*
	Access:
		private
*/

5 Example Code

Choose meaningful examples that depict the basics as well as interesting points or trouble areas.

Use a single tab to indent chunks of code.

In certain cases, especially for longer docs or more complex methods, you might need an 'Examples' section in the docblock.

/*
	Examples:
 		$this->model->find_by('field', 'value');
   		$this->model->find_by( array('field' => 'value', 'field2' => 'value2' ) );
*/

6 Filenames

As a rule of thumb, filenames listed in comments should be relative to the main bonfire folder, in a standard configuration.

application/core/MY_Model.php			# Good!
MY_Model.php							# Bad
bonfire/application/core/MY_Model.php	# Bad