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

Заметки - Фишки 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> — соответствует ли правило стандартам;