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:
- Javadoc for CSS (english)
- Adaption des Javadoc-Standards in CSS (deutsch)
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
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
- @debug
- @package, @subpackage [AptanaInfluence]
- @group [CssEdit]
Deprecitated
- @hack (hack) [depreciated-candidate]
- @hackfor (hack) [depreciated-candidate]
- @info (file, section) [depreciated; see @note]
- @browser (section)
Attachments
- cssdoc-cssfile-structure-00.png (4.9 kB) -
CSSDOC structure of a CSS File
, added by tom on 05/21/07 18:06:02. - cssdoc - 0.2.5.pdf (248.0 kB) -
CSSDOC First Public Draft Version 0.2.5
, added by tom on 11/03/07 14:00:34.
