mirror of
https://github.com/Karaka-Management/Developer-Guide.git
synced 2026-01-11 12:28:41 +00:00
199 lines
4.3 KiB
Markdown
Executable File
199 lines
4.3 KiB
Markdown
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:
|
|
|
|
```php
|
|
/**
|
|
* 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:
|
|
|
|
```php
|
|
/**
|
|
* 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:
|
|
|
|
```php
|
|
/**
|
|
* Member variable description.
|
|
*
|
|
* @var variable_type
|
|
* @since 1.0.0
|
|
*/
|
|
```
|
|
|
|
#### Function/Method
|
|
|
|
A function/method documentation MUST be implemented in the following form:
|
|
|
|
```php
|
|
/**
|
|
* 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:
|
|
|
|
```php
|
|
/** @var TestObject[] $myArray */
|
|
```
|
|
|
|
## JavaScript
|
|
|
|
The javascript documentation is based on JsDoc, therefore only valid JsDoc comments are valid for all js files.
|
|
|
|
### File
|
|
|
|
```js
|
|
/**
|
|
* 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:
|
|
|
|
```js
|
|
/**
|
|
* 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:
|
|
|
|
```js
|
|
/**
|
|
* 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.
|
|
|
|
```php
|
|
/** @var variable_type varName {optional_description}
|
|
```
|
|
|
|
## Todos
|
|
|
|
Todos should be documented in the [todo list](https://github.com/orgs/Karaka-Management/projects/10).
|
|
|
|
In code todos can be created like this
|
|
|
|
```php
|
|
// @todo Single line todo
|
|
// @bug Single line bug
|
|
// @security Single line security
|
|
```
|
|
|
|
```php
|
|
/**
|
|
* @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
|
|
*/
|
|
```
|
|
|