CSSDoc — формат комментариев для CSS
Уже неоднократно видел утверждение, что CSS необходимо комментировать, чтобы потом было проще сориентироваться себе или тому, кто также поддерживает или будет в дальнейшем поддерживать ваш код. Но почему-то никто не предлагает использовать какой-то универсальный формат комментариев, который был бы понятен всем, хотя в программировании такое используется повсеместно: JavaDoc, JSDoc, PHPDoc и т.п.
Несложно догадаться, что рано или поздно кто-нибудь бы захотел использовать подобный формат комментариев в CSS и такой формат появился: CSSDoc. Спецификация пока что имеет статус черновика, но ничто не мешает начать пользоваться основными правилами уже сейчас.
Полную спецификацию я приводить не буду, а приведу лишь часто используемые теги, причём акцент будет сделан не на автодокументировании, а на использовании CSSDoc для людей, так что некоторых вещей вы всё-таки из этого поста не узнаете, печально.
Формат комментариев полностью соответствует формату в JavaDoc и ему подобных:
@tag и @one-more-tag являются тегами. Они в совокупности с их значениями и являются самым главным оружием в документировании CSS. Теги описываются в документации и служат для определения каких-либо свойств присущих файлу/секции/правилу (подробнее об этом ниже).
Основные теги, которые вам наверняка захочется использовать:
А теперь, чтобы всё прояснилось напишем пример:
Как пользоваться остальными тегами, думаю, понятно. Пользуйтесь этим и тогданастанет мир во всём мире всем будет намного удобнее.
Кому интересно автодокументирование, то вот что получается в итоге.
Несложно догадаться, что рано или поздно кто-нибудь бы захотел использовать подобный формат комментариев в 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> — соответствует ли правило стандартам;
- @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.Как пользоваться остальными тегами, думаю, понятно. Пользуйтесь этим и тогда
Кому интересно автодокументирование, то вот что получается в итоге.
комментарии (75)