CSSDoc - comment format for CSS

I have already repeatedly seen the assertion that CSS needs to be commented, so that later it is easier to orient yourself or someone who also supports or will continue to support your code. But for some reason no one suggests using some kind of universal comment format that everyone would understand, although this is used everywhere in programming: JavaDoc , JSDoc , PHPDoc , etc.

It’s easy to guess that sooner or later someone would want to use a similar format for comments in CSS and this format appeared: CSSDoc . The specification still has draft status, but nothing prevents you from starting to use the basic rules now.


Full specificationI won’t cite it, but only frequently used tags, and the emphasis will not be on auto-documentation, but on the use of CSSDoc for people, so you still won’t learn some things from this post, it’s sad .

Comment Format

The format of the 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. They, together with their meanings, are the most important weapon in CSS documentation. Tags are described in the documentation and are used to determine any properties inherent in the file / section / rule (more on this below).

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

The main tags that you probably want to use:

• @package <name> - is indicated at the beginning of the file and indicates which library (project, etc.) it belongs to, i.e. serves to group files;
• @subpackage <name> - the same as @package, only means a group embedded 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 sense (reset, typography, layout), although nothing prevents us from using it as a division according to the structure of the document (header, footer);
• @subsection <name> - for dividing a file into subsections;
• bugfix <description> - description of the bugfix, here it is worth to describe briefly the essence of the bug;
• @workaround <description> - not to be confused with bugfix . It is worth pointing out when you use some non-trivial CSS for fairly simple things that are not related to browser bugs;
• affected <browsers> - list of browsers affected by the bug described in bugfix or @workaround. If it hurts all browsers, then you can not write;
• @ css-for <browsers> - a list of browsers for which the rule is written. It happens that some bugfix affected IE6, IE7, and we use the so-called rules We write "hacks" separately for IE6 and separately for IE7;
• @see <link> - when you need to specify a link to CSS files, in which there is something related to this particular case;
• @link <link> is just a link;
• @valid - whether the rule complies with standards;

The following do not need comments, but if someone is not clear, then 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

Example

And now, to make things clear we’ll write an example:

/**
* @package portal
* @version 0.1
* @author Joe Shmoe
*/

/**
* Это самый простой пример, поэтому используем самый
* простой 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 this and then there will be peace in the whole world it will be much more convenient for everyone.

Who cares about auto-documentation, here’s what’s the result .