web-dev-qa-db-ja.com

C＃またはVBドキュメントのコメントで太字または斜体？

ドキュメントコメント内でboldまたはitalicを使用する方法はありますか？何かのようなもの：

/// <summary>Cleanup method. This is <b>recommended</b> way of cleanup.</summary>
public void CleanAll();

事前定義されたタグのリスト そのような機能は含まれていませんが、強調/強調表示を実現する方法を知っていますか？コードにカーソルを合わせると、ツールチップにも表示されることが望ましいです。

我々は持っています <c>および<code>そこにありますが、それらにはすでにセマンティクスがあります。

c#vb.netvisual-studio-2015roslyn
16
miroxlav

この機能は、Visual Studio 2019バージョン16.3.0で利用できるようになりました（ リリースノート ）。

  • イタリックには、<i>または<em>タグを使用できます。
  • boldには<b>または<strong>タグを使用できます。
  • リリースノートから、さまざまなhtmlタグがサポートされているようですが、 公式ドキュメント はまだこの新機能で更新されていないようです。

次のようになります。 。

4
Batesias

OPのメモ：これは、2019 Visual Studioの更新前に受け入れられた回答であり、その後、他の回答を受け入れました。これは、その更新がなくてもユーザーにとって引き続き有用で有効です。

厳密ではありません。ただし、 Sandcastle （ドキュメントからHTMLを生成するドキュメントジェネレータ）は、そこでHTMLを使用することをサポートしているため、ビルドすれば<em>と<strong>を問題なく使用できます。サンドキャッスルと。

別の言い方をすれば、 Jamiec すでにメモしているように、XMLドキュメントのコメントは単なるXMLです。したがって、有効なXMLをそこに入れることができます。コンパイラはそれをドキュメントのXMLファイルに喜んで書き込みます。それはすべて、そのファイルを処理するソフトウェアに依存します。 Sandcastleは、それがとにかくその出力形式であるため、HTMLとして知らないものを渡すだけです。

Visual Studioは、ヘルプツールチップを表示するときにそれらを単に無視します。

その中のReSharper Ctrl+Q ビューはHTMLタグをテキストとして表示するため、少し見苦しくなります。

ただし、これらは通常、他の人が使用するライブラリを作成する場合にのみ関係します。しかし、それはまた、IDE内誰もあなたの強調を意図したとおりに見ることができないことを意味します。

APIドキュメントを作成するときに、強調する必要はほとんどありません。多くの場合、文を別の方法で記述したり、重要なノードを最後の近くの別の段落に配置して再構築したりして、強調する必要がまったくないようにすることができます。一貫した言語と言い回しは、読者が慣れたら重要なメモを拾うのにも役立ちます。

あなたのコードはおそらく単なる例でしたが、summaryは、タイプとメソッドが何であるかを短い文で記しているだけなので、何よりも強調する必要があると思います。どちらかといえば、備考欄に使ってみて、それでも実際に必要かどうか慎重に検討したいと思います。

12
Joey

強調を追加する他の方法があります：

 - Upper case:    some BOLD text       // you are shouting, but they WILL read it
 - First letter:  some Bold text       // less emphasis
 - Asterisks:     some **bold** text   // 2 asterisks seem to work best
 - Dashes:        some --bold-- text   // less emphasis

プレーンテキストは古風ですが、非常に効果的であり、テクノロジーが変更されてからずっと後に機能します。

3
user1023602

別の方法は、代わりにwikiマークアップのようなスタイルを使用することです。

/// <summary>Cleanup method. This is *recommended* way of cleanup.</summary>
public void CleanAll();

編集1： AFAIK VisualStudioはwikiマークアップを理解していません。慣例としてウィキマークアップを使用することを提案していました。チームは、メソッドのインテリセンスで未加工の（フォーマットされていない）wikiマークアップを引き続き表示します。

2
Antoni

<see cref = "YourReferenceHere" />（ ここを参照）に出くわしたときに、Intellisenseディスプレイに改行を追加しようとしていました。 ）、（ドキュメントによると）クリック可能な参照をドキュメントに挿入します。 Intellisenseのツールチップをクリックする方法はわかりませんが、参照を目立たせるのに役立つタイプ形式/色付きの表示を提供します（参照はIntellisenseで利用可能である必要があることに注意してください）。

補足：私は、単一の改行を行う方法を理解していませんでした。私が得ることができる最も近いのは、<para />タグを使用した二重改行です...

1
G Cook