CSSDoc - comment format for CSS

Already repeatedly saw the statement that CSS needs to be commented on, so that later it would be easier to orient yourself or someone who also supports or will continue to support your code. But for some reason, no one offers to use some kind of universal comment format that would be understandable to everyone, although in programming this is used everywhere: JavaDoc , JSDoc , PHPDoc , etc.

It is easy to guess that sooner or later someone would like to use a similar format of comments in CSS and such a format appeared: CSSDoc . The specification still has the status of a draft, but nothing prevents to start using the basic rules now.


I will not give a complete specification , but I will cite only frequently used tags, and the emphasis will be not on autodocument, but on using CSSDoc for people, so you will not learn some things from this post, sadly .
')

Comment format

The format of comments is fully consistent with the format in JavaDoc and the like:

/**
* — !
*
* ,
*
*
* @tag
* @one-more-tag true
*/

* This source code was highlighted with Source Code Highlighter .

Tags

tag and @ one-more-tag are tags. These, together with their meanings, are the most important weapon in documenting CSS. Tags are described in the documentation and are used to define any properties inherent in the file / section / rule (more on this below).

Funny fact: according to the specification, the value of the tag cannot be a unicode string, to which we will unite together, because the specification is still draft, and this restriction is, to put it mildly, delusional in our age.

The main tags that you probably want to use:

• @package <name> - is specified at the beginning of the file and indicates which library (project, etc.) it is in, i.e. serves to group files;
• @subpackage <name> - the same as @package, only means a group nested in @package, for example: some part of a project or library;
• @section <name> - to divide the file into sections. The specification states that the main purpose is partitioning by meaning (reset, typography, layout), although nothing prevents you from using as a division according to the structure of the document (header, footer);
• @subsection <name> - to divide a file into subsections;
• bugfix <description> - description of the bugfix, here it is worth describing briefly the essence of the bug;
• @workaround <description> - not to be confused with bugfix . It is worth pointing out when you use any non-trivial CSS for fairly simple things, not related to browser bugs;
• affected <browsers> - a list of browsers that are affected by the bug described in bugfix or @workaround. If it affects all browsers, then you can not write;
• @ css-for <browsers> - the list of browsers for which the rule is written. It happens that some bugfix is affected by IE6, IE7, and we use the rules so-called. Hacks are written separately for IE6 and separately for IE7;
• @see <link> - when you need to specify a link to the CSS files in which there is something related to this particular case;
• @link <link> is just a link;
• @valid <yes / no / true / false> - whether the rule complies with the standards;

The following do not need comments, but if it is not clear for someone, you can see the Russian-language documentation for JavaDoc or PHPDoc (I hope they exist):

• @todo brush your teeth!
• @author <name>
• @copyright Copyright 0-2010 by Evil Empire
• @license <license type>
• @date <date>
• @lastmodified <date>
• @version <version>
• @since <version>
• @revision <revision>
• @ since-revision <revision>

Example

And now, so that everything clears up, let's write an example:

/**
* @package portal
* @version 0.1
* @author Joe Shmoe <joe@shmoe.com>
*/

/**
* ,
* reset
*
* @section reset
* @link www.google.com/search?q=reset+css
*/
* {
margin: 0;
padding: 0;
}

/**
*
*
* @section common
*/

/**
* @subsection inline-blocks
*/
.inline-block {
display: inline-block;
}

/**
* .. -
*
*
* @bugfix IE inline-blocks support
* @link www.google.com/search?q=ie+inline-block
* @affected IE6, IE7
* @css-for IE6
* @valid no
*/
* html .inline-block {
display: inline;
zoom: 1;
}

/**
* @bugfix IE inline-blocks support
* @link www.google.com/search?q=ie+inline-block
* @affected IE6, IE7
* @css-for IE7
* @valid no
*/
*+html .inline-block {
display: inline;
zoom: 1;
}

* This source code was highlighted with Source Code Highlighter .

How to use the rest of the tags, I think, is understandable. Use it and then peace will come to all around the world will be much more convenient.

Who is interested in autodocumenting, that's what comes out of it .