Documentation
Documentation resources
README.md
Your module directory should contain a README.md
file. We recommend using the markdown format.
The file should provide basic information about the extension, e.g.:
Title – the name of the module
Author – the author/company of the module
Prefix – the prefix you use
Version – version of the module which is described
Link – a link to the homepage of the author/company
Mail – email for contact
Description – a short description of the function of the module
Installation – a detailed description how to install the module
Modules – which other modules are used
Resources – other resources
Here is a (shortened) example:
The ... extension for OXID eShop 6
==================================

### List of features
* List item A
* List item B
* List item C
### Setup
For installation instructions please see...
### Module installation via Composer
Install this module...
CHANGELOG.md
The file CHANGELOG.md
should contain a description of the changes that were added for each release.
The latest releases should be on top of that file.
A simple example:
### 1.0.1
* Fixed a bug that prevented...
### 1.0.0
* Completed all features, tested and stable.
PHPDoc
You can provide a HTML document that contains the PHPDoc from the code’s comments. See also PHP comments.
Documentation directory
You can provide additional documentation materials inside a documentation
directory (within the directory structure of
the module), e.g. in PDF files.
PHP Comments
Add comments to your code. Each class, variable and method should have a comment. A comment should give additional information and not only repeat the name. See the following example:
<?php
/**
* Cupboard
*
* @package Furniture
* @version $Revision$
* @author
* @copyright Copyright (C) 2003-2017 SomeCompany . All rights reserved.
* @license http://www.gnu.org/licenses/gpl-3.0.txt GPL
* @extend Base
*/
class Cupboard extends Cupboard_parent
{
/**
* Number of cups in the cupboard. Declared in units
*
* @var int
*/
protected $numberOfCups;
/**
* Take a cup from cupboard
*
* Reduces the amount of cups by the specified amount. If
* there are not enough cups left the cupboard is emptied. The actual amount
* of cups removed from the cupboard will be returned.
*
* @extend drink
* @param int $amount
* @return int
*/
public function take( $amount )
{
// inline comment
$this->numberOfCups -= $amount = max( $this->numberOfCups, $amount );
return $amount;
}