インテリセンス

intellisense.png

 インテリセンスに自分のコメントを反映させるには?

概要

この文法はECMA標準らしくて、C#で使われているもののようだ。

<?xml version="1.0"?>
<doc>
    <assembly>
        "ConvertSolutionToKml"
    </assembly>
    <members>
        <member name="M:CSolutionHeader.DataType1(System.Byte)">
            <param name="_val">_valを渡すと、情報を返してくれる</param>
        </member>
        <member name="M:CBlockHeader.Info">
            <summary>
 これ???.
</summary>
            <remarks>
こねんとだよ~
</remarks>
        </member>
    </members>
</doc>

使い道

クラスやメソッドの説明をIntelliSenseに表示したり、
ツールを使ってクラスライブラリのリファレンスドキュメントを作成したりすることが出来る。
ここの説明がわかりやすい
XML コメントの summary コンテンツが表示されます。
sandcastleでXMLからHTML作成?
sandcastleの使い方
sandcastle Help File BuilderというGUIのついているソフトはまた別にインストールしなければならないらしい。
Sandcastle Styles patch.も必要

XMLドキュメントコメントの要素

説明文を記述するための要素

要素 JavaDoc 用途と意味
summary brief 型やメンバに関する説明・概要を記述します。
この要素は他の要素を含むことも出来、他の型やメンバへのリンクとなるsee要素や段落を表すpara要素などを使って記述することが出来ます。
remarks detaled description 型やメンバに関する補足的な追加の情報を記述します。
この要素でsummary要素の記述を補足します。 summary要素と同様、see要素やpara要素を使って記述する事も出来ます。
param a param name="name"…/param 指定された引数nameに関する説明を記述します。
この要素で引数に指定できる値や、値域についての説明を記述します。 ArgumentExceptionなどの例外について記述するにはexception要素を使います。
returns return メソッドの戻り値に関する説明を記述します。
exception exception cref="member"…/exception メンバがスローする例外に関する説明を記述します。
cref属性でスローする例外、要素のテキストでその例外がスローされる理由・状況についての説明を記述します。 cref属性の指定方法はメンバのID
example doxygenでは無視される 型やメンバの使用例について記述します。
see要素やpara要素の他に、インラインのコードはc要素、複数行にまたがるコードはcode要素を使って記述することが出来ます。
value doxygenでは無視される プロパティが表す値について記述します。

リンクを作成するための要素

paramref要素 a paramref name="name"/ 指定された引数nameの説明へのリンクを指定します。
see要素 ref see cref="member"/ 指定されたメンバmemberへのリンクを指定します。 memberには任意の型やメソッドを指定することが出来ます。 cref属性の指定方法はメンバのID

説明文の文書構造を定義するための要素

para para…/para 説明文の段落を定義します。 これはXHTML/HTMLのp要素やdiv要素に相当する要素です。
c c…/c インラインで表示されるコードを記述します。 説明文中の変数名やメソッド名などを修飾する場合に使います。
code code…/code 複数行のコードを記述します。

コメントの書き方

  • ///…1行コメント
  • /** */….複数行コメント

有効な書き方

/// <summary>概要</summary>
/** <summary>text</summary> */
/**
<summary>text</summary>
*/
/**
* <summary>
* text </summary>*/

ダメな書き方

/**
* <summary>
text </summary>*/

textの部分が認識されない。

documentation

サポートサイト Wikidot.com documentation