CSSDOC is a commenting convention much like Java Doc and PHP Doc. It provides a standard way for developers to tag parts of a stylesheet with important meta information. Eventually it may be used to provide an enhanced interface in your favorite IDE. Although it is still in the draft phase, CSSDOC is a great way to clean up your stylesheets.
Syntax
This is the basic block in which all comments will be placed. It has a very specific markup. The opening line has one forward slash followed by two asterisks. Each comment line thereafter should start with a single space an asterisk and one more space. Note: spaces do not show up in the examples unless you click the PLAIN TEXT link. Finally to end the block use a single space, one asterisk, and another forward slash.
[css]
/**
*
*/
[/css]
A tag is a single at sign (@) followed by some text with no space. Most tags can be followed by a single space and some descriptive text, as follows:
[css]
/**
* @tag This is a tag!
*/
[/css]
Additionally, each block may contain several lines that do not have tags. These lines are typically reserved for a title and long description:
[css]
/**
* Descriptive Title
*
* Your long description would go here, before any of the tags.
*/
[/css]
File comment
Most designers want to put a little title block at the top of their stylesheets. It will usually include information about the author and creation date. There are a lot of tags, I have included the most common ones in the example below.
[css]
/**
* Stylesheet title
*
* Your stylesheet description would go here.
*
* @project Name
* @version 1.0
* @author Name
* @copyright Year
* @license Type
*/
[/css]
Section and Subsection Comment
You can mark a section in your file with @section and @subsection tags. You can title these areas but I typically find myself dropping the title and just including the section name.
[css]
/**
* @section Section
*/
[/css]
One thing that CSSDOC lacks is a method for defining visual delineation between sections in a stylesheet. This should be left to the IDE. Unfortunately, I am not aware of any IDEs that support CSSDOC. I suggest this simple compromise for the time being.
[css]
/**
* ————————-
* @section Section
* ————————-
*/
[/css]
Visually it works pretty well. Someday CSS editors may incorporate the CSSDOC standard and render a visual indicator for section tags.
Bug/Workaround Comment
It’s a sad but true fact that we have to use hacks to fix browser display issues. Fortunately CSSDOC provides a great way to mark these sections of code.
[css]
/**
* Why the fix is here
*
* @workaround or @bugfix
* @affected browser
* @valid yes or no
*/
[/css]
The workaround/bugfix syntax is a little confusing to me. Here is the explanation from the draft:
Bugfix: Should remove CSS-Rendering Problems without having bothersome effects.
Workaround: Some browsers need a reduced rendering because they are full of errors. A Workaround works around those Issues.
They list the Guillotine bug as a workaround and the disappearing list-background bug as a bugfix. I don’t get it. Instead, I would prefer to combine both tags into one, such as @hack or @fix.
You can also document the affected browser and whether or not the hack is valid. For a complete list of browser codes check the appendix in the draft.
I have wondered what to do about a simple hack, like a display:inline to prevent the double float margin bug. You don’t want to put it in a huge block of its own and you don’t want to put a CSSDOC block inside of a declaration. So what do you do? I don’t know. Maybe this will be addressed in the technical spec.
Other Useful Tags
@colordef: For notating colors. Follow it with a #color and a description of what it is used for.@see: If you need to reference a website you can drop a link after this tag. It’s nice to give attribution.@todo: I use this one all the time. Whenever you need to remember what you have to do next you can use this tag.
Conclusion
CSSDOC is a great way to standardize your stylesheet comments. It provides a nice framework for adding rich meta information to your CSS that might otherwise be lost. Someday we may even see it implemented in an IDE. If you are interested in finding out more, download the Public Draft.
