CSS Automatic Documentation
CSSdoc Comments use the standard CSS block comments, but apply some commands directly after the comment opener.
/*[!|-|=|demo] ... */
The project indicator should be used for the first comment in your stylesheet.
The equal character defines a new module.
The minus character defines a new element.
The demo command defines a new code example.
The project can be defined anywhere in your stylesheet files, but its best practice to define it in a comment at the very beginning of your main CSS file.
/*! Project Title/Headline A project description that can be multiple lines long. Just as you wish. @version 1 @used http://example.com/ */
The CSS documentation is structured in modules and elements.
To indicate that something belongs to a certain module, use the @module parameter, like so:
@module: my module name
A module itself is defined by using the exclamation mark as first character in the comment block:
/*= My Module Headline Some module description which goes deeper and explains more. @module mymodule */
The first line in the module definition is the modules headline.
The second, and any other following headline is considered as module description.
Finally use the @module parameter to indicate the belonging.
To get a visual separation in your CSS file, you can repeat the "=" character at the beginning as many times as you want:
So what is considered as a module?
Well, everything you can pack together because it logically belongs to each other.
For example all button styles, all link styles, or all form styling.
An Element in CSSdoc represents all CSS rules used on a single visual Element in HTML.
This can be a item in your shopping bag, or the shopping bag itself. Its up to your decision.
Introduce a new element like so:
/*- An example Element This is my explanation on the example element. @module mymodule */
All CSS-Rules following the element definition are assigned to the element, until a new element definition is set, or the file ends.
To get a visual separation in your CSS file, you can repeat the "-" character at the beginning as many times as you want:
To have visual representation of the CSS-Classes you can embed markup examples in the CSSdoc. Introduce them like so:
/*demo <a href="#" class="myclass">This is a example link</a> */
Code demos are assigned to the last introduced element.
Use this tag to define an author for an element. It can either be only the authors' name, or append a connection in <> brackets. Example:
@author Christian Engel <firstname.lastname@example.org>
Can be used on modules and elements to show the revision they are currently in.
You may as well append a date after the version number.
@version: 12 2011-10-26
Can be used on modules and elements to show in which revision they have been implemented.
This indicates that the following element is, or will be deprecated in the future. Define a upcoming version number to indicate that the element will be deprecated then.
Alternatively any string can be placed as well:
@deprecated Will be used no more since 2011-11-13
Can be used on the project, modules and elements to link to a real world example where the styles are used.
The TODO marker indicates if something has to be done on either projects, modules or elements.
@TODO Make layout responsive
This displays a hyperlink to a url for a license. Can be used in the project definition block. Its made of two parts - the URL and a title, separated by comma.
@license http://opensource.org/licenses/gpl-license.php GNU Public License
This tag is used to apply copyright information to the CSS document.
It can be used on the project definition block.
@copyright Copyright (c) 2012, Kiss