CSSDoc — формат комментариев для CSS

Уже неоднократно видел утверждение, что CSS необходимо комментировать, чтобы потом было проще сориентироваться себе или тому, кто также поддерживает или будет в дальнейшем поддерживать ваш код. Но почему-то никто не предлагает использовать какой-то универсальный формат комментариев, который был бы понятен всем, хотя в программировании такое используется повсеместно: JavaDoc, JSDoc, PHPDoc и т.п.

Несложно догадаться, что рано или поздно кто-нибудь бы захотел использовать подобный формат комментариев в CSS и такой формат появился: CSSDoc. Спецификация пока что имеет статус черновика, но ничто не мешает начать пользоваться основными правилами уже сейчас.


Полную спецификацию я приводить не буду, а приведу лишь часто используемые теги, причём акцент будет сделан не на автодокументировании, а на использовании CSSDoc для людей, так что некоторых вещей вы всё-таки из этого поста не узнаете, печально.

Формат комментариев

Формат комментариев полностью соответствует формату в JavaDoc и ему подобных:

/**
* Я — оригинальный комментарий!
*
* У меня даже есть немного текста, который точно так же
* оригинален и возможно даже несколько забавен
*
* @tag Значение тега
* @one-more-tag true
*/

* This source code was highlighted with Source Code Highlighter.

Теги

tag и @one-more-tag являются тегами. Они в совокупности с их значениями и являются самым главным оружием в документировании CSS. Теги описываются в документации и служат для определения каких-либо свойств присущих файлу/секции/правилу (подробнее об этом ниже).

Забавный фактик: по спецификации значением тега не может быть unicode-строка, на что мы дружно забьём, ибо спецификация ещё черновая, да и ограничение это в наш век является, мягко говоря, бредовым.

Основные теги, которые вам наверняка захочется использовать:

• @package <имя> — указывается в начале файла и указывает в какую библиотеку (проект и т.п.) он входит, т.е. служит для группировки файлов;
• @subpackage <имя> — то же, что и @package, только означает вложенную в @package группу, например: какая-то часть проекта или библиотеки;
• @section <имя> — для разделения файла на секции. В спецификации указано, что основным назначением является разбиение на секции по смыслу (reset, typography, layout), хотя ничто не мешает использовать как разделение соответственно структуре документа (header, footer);
• @subsection <имя> — для разделения файла на подсекции;
• bugfix <описание> — описание багфикса, здесь стоит описать кратко суть бага;
• @workaround <описание> — не путать с bugfix. Стоит указывать когда вы используете какой-либо нетривиальный CSS для довольно простых вещей, не связанных с багами браузеров;
• affected <браузеры> — список браузеров, на которые распространяется влияние бага, описанного в bugfix или @workaround. Если это задевает все браузеры, то можно не писать;
• @css-for <браузеры> — список браузеров, для которых написано правило. Бывает, что какой-либо bugfix affected IE6, IE7, а правила мы с помощью т.н. «хаков» пишем отдельно для IE6 и отдельно для IE7;
• @see <ссылка> — когда нужно указать ссылку на CSS файлы, в которых встречается что-то связанное с данным конкретным случаем;
• @link <ссылка> — просто ссылка;
• @valid <yes/no/true/false> — соответствует ли правило стандартам;

Следующие в комментариях не нуждаются, но если кому-то будет непонятно, то можно посмотреть русскоязычную документацию к JavaDoc или PHPDoc (надеюсь они существуют):

• @todo Почистить зубы!
• @author <имя>
• @copyright Copyright 0-2010 by Evil Empire
• @license <тип лиценции>
• @date <дата>
• @lastmodified <дата>
• @version <версия>
• @since <версия>
• @revision <ревизия>
• @since-revision <ревизия>

Пример

А теперь, чтобы всё прояснилось напишем пример:

/**
* @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.

Как пользоваться остальными тегами, думаю, понятно. Пользуйтесь этим и тогда настанет мир во всём мире всем будет намного удобнее.

Кому интересно автодокументирование, то вот что получается в итоге.