XMLコメント - 例外の複数の理由をコメントする方法は? -- exception フィールド と xml-comments フィールド 関連 問題

XML Comments - How to comment multiple reasons for an exception?












8
vote

問題

日本語

これは例です:

<事前> <コード> public void DoSomething(String param1, String param2) { if (param1 == null) throw new ArgumentNullException("param1"); if (param2 == null) throw new ArgumentNullException("param2"); }

2 ArgumentNulLExceptionの理由が異なります。 msdns string.format例<コード> FormatException の2つの異なる理由を示します。だから、それはこのようにして行われます:

<事前> <コード> /// <exception cref="ArgumentNullException"> /// <paramref name="param1"/> is null. /// </exception> /// <exception cref="ArgumentNullException"> /// <paramref name="param2"/> is null. /// </exception>

またはその他の方法は?

<事前> <コード> /// <exception cref="ArgumentNullException"> /// Some other way to show the 2 reasons with an "-or-" between them. /// </exception>
英語

Here's an example:

public void DoSomething(String param1, String param2) {     if (param1 == null) throw new ArgumentNullException("param1");     if (param2 == null) throw new ArgumentNullException("param2"); } 

2 different reasons for an ArgumentNullException. MSDNs String.Format Example shows 2 different reasons for the FormatException. So, is it done this way:

/// <exception cref="ArgumentNullException"> ///     <paramref name="param1"/> is null. /// </exception> /// <exception cref="ArgumentNullException"> ///     <paramref name="param2"/> is null. /// </exception> 

or some other way?

/// <exception cref="ArgumentNullException"> ///     Some other way to show the 2 reasons with an "-or-" between them. /// </exception> 
</div
     

回答リスト

14
 
vote
vote
ベストアンサー
 

ドキュメントの各行が1つの <exception cref=...> </exception> であると思う場合は、論理的にそれを行う方法をあなたの2番目の代替手段を使用しています:

<事前> <コード> /// <exception cref="ArgumentNullException"> /// <p><paramref name="param1"/> is null. </p> /// <p>- or - </p> /// <p><paramref name="param2"/> is null. </p> /// </exception>

行を示すために 'P'要素を使用できます。

 

If you think each of the rows of the docs as being one <exception cref=...> </exception>, then logically the correct way to do it is using your second alternative:

/// <exception cref="ArgumentNullException"> ///     <p><paramref name="param1"/> is null. </p> ///     <p>- or - </p> ///     <p><paramref name="param2"/> is null. </p> /// </exception> 

You can use 'p' elements to denote the lines.

</div
 
 
   
   

関連する質問

27  CapaniationManagerがSave()でXMLコメントを保持できますか?  ( Can configurationmanager retain xml comments on save ) 
私は私が別のアプリケーションのapp.configファイルの単純なAppsettingを変更することを可能にする小さなユーティリティを書いてから、変更を保存します: <事前> <コード> //save a backup copy first. var cf...

1  Visual Studio 2010のC ++でのXMLコメントを有効にする  ( Enabling xml comments in c in visual studio 2010 ) 
Visual Studio 2010のC ++メソッドALA C#とVBのXMLコメントを有効/達成する方法は?この機能がデフォルトで有効/使用可能ではないようです。 最初に管理されたC ++プロジェクトをターゲット化します。 ...

2  Sandcastle 1タブコントロールで複数のコード例  ( Sandcastle multiple code examples in one tab control ) 
Sandcastle内のコード例を使用しているのに問題があります。 1つのタブコントロールで4つの例を持つことができるが、これを行う方法はわからない。 <事前> <コード> /// <summary> /// AnimatedExpander inherit...

2  XMLコメント:使用するか使用しないことは?  ( Xml comments to use or not to use ) 
私の共同労働者はめったにXMLのコメントを使うことはめったにありません(私は私がより良いと言うことはできません)。私は最近それらを使用する利点を見ましたが、彼らが文書化しているコードが明確に書かれていれば本当に価値がありますか(表現/説明的な変数/関数名、いく...

2  Visual StudioのJavaScript - クロージャスタイルのコメント  ( Javascript in visual studio closure style comments ) 
Visual Studioでクロージャスタイルのコメントを使用してサポートするプロジェクトを誰もが知っていますか? マイクロソフトにはXMLのコメントがありますが、Ajax Minifierがコードを最適化するためにそれらを使用しない限りではありません。理...

0  C#XMLコメント、CREFは基本クラスで定義されているリファレンスメソッドを参照できません  ( C sharp xml comment cref cant reference method defined in base class ) 
マイコードベースでは、基本クラスで定義されているメソッドがあり、基本クラスは継承されますが、メソッドはまだ上書きされていません。このメソッドは、将来的には基本実装に追加することが非常に高くなります。 私の設定はこのような少し見えます: <事前> <コード> p...

3  GDataxMLをコメントを無視するにはどうすればよいですか。  ( How can i make gdataxml ignore comments ) 
GDATAXMLがこの行を解析したとき <事前> <コード> <choices array="YES" > <!-- for now, the first answer is the right one --> コメント for now, the fir...

1  派生クラスまたはインタフェース実装のソースコードにおけるXMLコメント  ( Xml comments in source code for derived classes or interface implementations ) 
前の質問に関連しています。インターフェースを定義した場合、私はそのメンバーをコメントします。その後、元のコメントが無効になっていない理由がない限り、実装クラスの実装をコメントしないでください。 再充電器はこれで問題ありません、Visual Studioは警告...

9  XMLコメントのサポートされている文字エンティティは何ですか?  ( What are the supported character entities for xml comments ) 
次の例では、 &amp; と &#916; は大丈夫ですが、 &Delta; < /コード> はありません(後者の2つは両方ともΔ)です。コンパイラは、次のような警告を発行します。 <前> 警告CS1570: 'xxx.documentedMetho...

19  NET XML APIドキュメントへのコメント  ( Net xml comment into api documentation ) 
Visual Studio XML出力からMSDNスタイルのマニュアルを作成する簡単な方法はありますか? 私はこの橋を渡る最初の人ではないことを知っているので、私はそれのために良いXSLTを設定するのに十分な患者ではありません。 また、最近Sandcast...




© 2022 cndgn.com All Rights Reserved. Q&Aハウス 全著作権所有