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ドキュメンテーションで最も重要な
武器です。 タグはドキュメントに記載されており、ファイル/セクション/ルールに固有のプロパティを決定するために使用されます（詳細は以下）。
おもしろい事実：仕様によれば、タグの値はユニコード文字列にはなり得ません。これは一緒に採点します。なぜなら、仕様はまだ草案であり、この制限は私たちの時代ではおおざっぱに言えばクレイジーです
おそらく使用したい主なタグ：
- @package <name> -ファイルの先頭に示され、それが属するライブラリ（プロジェクトなど）を示します。 ファイルをグループ化するのに役立ちます。
- @subpackage <name> -@packageと同じ。@ packageに埋め込まれたグループのみを意味します。たとえば、プロジェクトまたはライブラリの一部。
- @section <name> -ファイルをセクションに分割します。 仕様では、主な目的は感覚による分割（リセット、タイポグラフィ、レイアウト）ですが、ドキュメントの構造（ヘッダー、フッター）に応じた分割として使用することを妨げるものはありません。
- @subsection <name> -ファイルをサブセクションに分割します。
- バグ修正 <description> - バグ修正の説明 。ここでは、バグの本質を簡単に説明する価値があります。
- @workaround <description>-bugfixと混同しないでください。 ブラウザのバグに関係しないかなり単純なことのために、ある種の重要なCSSを使用する場合、指摘する価値があります。
- 影響を受ける <browsers> - バグ修正または@workaroundで説明されているバグの影響を受けるブラウザーのリスト。 それがすべてのブラウザを傷つけるなら、あなたは書くことができません。
- @ css-for <browsers> -ルールが記述されているブラウザーのリスト。 いくつかのバグ修正 が IE6、IE7に影響を与えたため、いわゆるルールを使用しています。 IE6とIE7で別々に「ハック」を作成します。
- @see <link>-CSSファイルへのリンクを指定する必要がある場合。この特定のケースに関連するものがあります。
- @link <link>は単なるリンクです。
- @valid <yes / no / true / false> -ルールが標準に準拠しているかどうか。
以下はコメントを必要としませんが、誰か不明な場合は、JavaDocまたはPHPDocのロシア語のドキュメントを見ることができます（存在することを望みます）。
- @todo歯を磨く！
- @author <名前>
- @copyright Copyright 0-2010 by Evil Empire
- @license <ライセンスタイプ>
- @date <日付>
- @lastmodified <日付>
- @version <バージョン>
- @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 .
残りのタグの使用方法は理解できると思います。 これを使用すると
、世界中に平和がもたらされ、誰にとってもはるかに便利になります。
自動文書化を気にする人、
結果は次の
とおりです。