

# CHIP Guide for Documentation

*A mostly reasonable approach to write comments inside your projects*


## Stylesheet (CSS, SCSS)
Each CSS-Block should be documented to automatically generate a documentation with example markup.
The documentation is based on [DSS (Documented Style Sheet)](https://github.com/DSSWG/DSS)
 
 

  ```javascript
    /**
      * @name Default Colors group
      *
      * @description The default color set for chip.de page.
      *
      * @class chip-red { background-color: #F00; }
      *
      * @state .chip-red - Chipred
      * @state .chip-green - Chipgreen
      *
      *
      * @markup
      *   <div class="btn-group">
      *      <button class="btn btn-default %chip-red"> hibba </button>
      *      <button class="btn btn-default">Middle</button>
      *      <button class="btn btn-default">Right</button>
      *   </div>
      */
   ```
#### Possible attributes for the CSS-documentation:
  +    **@name**: the name of the CSS-Section
  +    **@description**: Documents the description of an CSS-Block. 
  +    **@state**: Document a state for the Button, like modifiers. For each state it builds a Subversion of the markup. ( Syntax: *name - type - description* ) 
  +    **@markup**: Documents an example HTML-Markup for a showcase for the CSS(lines till next @ are the Markup)
  
#### Optional Information:

   
   
## Javascript
In general the code should be so simple and broken down in small blocks, that each function should be 
readable without a necessary of comments. The documentation is based on [JSDoc](http://usejsdoc.org/)
 
At the moment not every JSDOC-tag is parsed but it will be an ongoing process.
### **Module Documentation**

- The first comment-type is the commentblock for the module. It should be defined as the first
Commentblock inside of the file.

   ```javascript
    /*
    * @module taze
    * @name Modul-Beschreibung
    * @author CHIP Digital GmbH
    * @version 0.0.1
    * @description Modul zum Beschreiben der Dokumentation
    * @namespace ModuleNamespace
    */
   ```
   
#### Possible attributes for the module-block:
   +    **@module**: General name of the module
   +    **@name**: in the module it is used to define the headline for the generated block
   +    **@author**: Identify the author of an module
   +    **@version**: Documents the version number of an module. 
   +    **@description**: Documents the overall functionality of a module. 
   +    **@member**: Document a member/variable of a module. ( Syntax: *name - type - description* ) 
   +    **@namespace**: Documents a namespace object
   
#### Optional Information:
   
   
### **Function Documentation**

- Within the module each function needs a basic description of it usage, which parameter a function needs 
and if a value is returned which type to expect.

    ```javascript
    /*sk
    * @name Funktion: taze ()
    * @deprecated
    * @description  Beispielfunktion für die JSDocs Documentation
    * @param victim - {object | array} - none - the victim(s) to fry
    * @param crazyHair - {boolean} - [crazyHair=true] - optional spikey hair effect
    * @return {external:Promise} - nothing - ladida text
    */
    ```
    
#### Possible attributes for the function-block:
   +    **@module**: General name of the module
   +    **@name**: name of the function
   +    **@description**: Documents the functionality of a function. 
   +    **@param**: Document the parameter to a function. ( Syntax: *name - type - default value - description* ) 
   +    **@return**: Document the return value of a function. ( Syntax: *expected type - default value - description** )
   
   
#### Optional Information:
   +    **@deprecated**: (optional) Document that this is no longer the preferred way.

## PHP Source Code 
** more to come ** 

### Module Documentation

### Function Documentation

