CSSDOC Draft

Status of this Document

This document is in the process of being written. If you want to get a first insight, you can additionally read the originating articles about the topic:

But this document already contains information and is publicly viewable. So please keep in mind that everything on this page and in the draft is subject to change and incomplete. Some part of the draft might even disappear completely.

CSSDOC First Public Draft PDF-File

Concept

By using CSSDOC additional relevant information can be placed into CSS comments. This is done by using the concept of DockBlocks. This concept of Short/Long comment and @tag-tags can be easily used within CSS as well. This document suggests how DocBlock and Tags are used. If you don't know what both are, please learn about those things before you continue.

Structure of a CSS File

CSSDOC structure of a CSS File This might be incorrect but currently we think that any CSS File is not structured or structured into sections. CSSDOC divides the file into different parts which are defined by one File-DocBlock and zero or more Section-DocBlocks. The File-DocBlock will open the file, a Section-comment starts a new section. At the end of a section you can additionally place one or more Hack-Comments if you feel in the need to comment so called CSS-Fixes or CSS-Hacks.

Next to these parts of a file, each DocBlock can and sometimes must contain certain tags. This differs from existing tags and their usage in PHP or Java, because CSS is not a programming language. But some parts are quite comparable because CSS files are being written.

Main DocBlock and comment types in CSSDOC

Tags in CSSDOC

File Information

  • @author (file)
  • @copyright (file)
  • @date (file)
  • @version (file)
  • @revision (file)
  • @since (file, section)
  • @license (file)
  • @link (file)
  • @lastmodified (file)
  • @media (file, section)
  • @site (file)
  • @style (file)

Descriptive Tags

  • @appdef (file)
  • @app- (file; section)
  • @colordef (file; section)
  • @note (file, section, comment)
  • @ref (section)
  • @section (section)
  • @see (file, section)
  • @tested (file, section, comment)
  • @todo (file, section, comment)

Bugfixes and Workarounds

  • @workaround (section, comment) helper for many things - like many bugs / prevent one or more bugs to appear
  • @bugfix (section, comment) fixing a specific bug
  • @affected (section)
  • @css-for (section)
  • @valid (section)

Candidates

Upcoming

Deprecitated

  • @hack (hack) [depreciated-candidate]
  • @hackfor (hack) [depreciated-candidate]
  • @info (file, section) [depreciated; see @note]
  • @browser (section)

Attachments