4.3 KiB
Executable File
Documentation
Module
Every module must have two types of documentation. One for the end-user, which also includes information for the administrator and module configuration and another documentation for developers. Documentation must be available in at least English language.
User
The user documentation should cover the following aspects:
- Installation, update, status change and delete process
- Dependencies and requirements
- Configuration options
- Permission management
- How to use the module and its functionality from an end-user perspective
Developer
The developer documentation should cover the following aspects:
- Database UML diagram (incl. relations to other modules)
- How to interact with the controllers, views and models from other modules
- How to interact with the controllers, views and models from within the module
- Best practices (does and don'ts)
- Module specific guidelines & contribution information
Database
Diagrams
Every module that has a database table must implement a UML diagram illustrating the internal table relations as well as the relations with external tables from other modules.
Php
The php documentation is based on PhpDocumentor, therefore only valid PhpDocumentor comments are valid for files, classes, functions/methods and (member) variables.
File
A file documentation MUST be implemented in the following form:
/**
* File description
*
* PHP Version 7.0
*
* @package Package name
* @copyright Karaka
* @license OMS License 1.0
* @version 1.0.0
* @link http://your.url.com
*/
Class
A class documentation MUST be implemented in the following form:
/**
* Class description.
*
* @package Package name
* @license OMS License 1.0
* @link http://your.url.com
* @since 1.0.0
*/
Member
A member variable documentation MUST be implemented in the following form:
/**
* Member variable description.
*
* @var variable_type
* @since 1.0.0
*/
Function/Method
A function/method documentation MUST be implemented in the following form:
/**
* Function/method description.
*
* Optional example or more detailed description.
*
* @param variable_type $param1Name Parameter description
* @param variable_type $param2Name Parameter description
*
* @return return_type
*
* @since 1.0.0
*/
Variable
Variable documentation is not mandatory and can be omitted. However it's recommended to use a variable documentation for objects and arrays of objects in templates for IDE code completion.
Example:
/** @var TestObject[] $myArray */
JavaScript
The javascript documentation is based on JsDoc, therefore only valid JsDoc comments are valid for all js files.
File
/**
* File description.
*
* @package Package name
* @copyright Karaka
* @license OMS License 1.0
* @version 1.0.0
* @link http://your.url.com
*/
Class
A class documentation MUST be implemented in the following form:
/**
* Class description.
*
* @package Package name
* @license OMS License 1.0
* @link http://your.url.com
* @since 1.0.0
*/
Member
Function/Method
A function/method documentation MUST be implemented in the following form:
/**
* Function/method description.
*
* Optional example or more detailed description.
*
* @param {variable_type_1} param1Name Parameter description
* @param {variable_type} [optionalPara] Parameter description
*
* @return {return_type}
*
* @since 1.0.0
*/
Please also note the correct alignment of @param type, name and description
Variable
In some cases it may be required to type hint a variable in this case the following format MUST be used.
/** @var variable_type varName {optional_description}
Todos
Todos should be documented in the todo list.
In code todos can be created like this
// @todo Single line todo
// @bug Single line bug
// @security Single line security
/**
* @todo Multi line todo
* This way developers can see todos directly in the code without going to an external source.
* Todos must not have empty lines in their descriptions.
* If the external ressources have empty lines they must be removed in the todo comment.
* 1. list item 1
* 2. list item 2
*/