web-dev-qa-db-ja.com

ソースコードのドキュメントにMarkdownを使用する

私は、C＃のXMLソースコードドキュメントに代わるものを探しています。これは、XMLの性質上、目に重く、書く作業が増える多くのノイズをもたらします。

/// <summary>
/// This is text of importance. Linking to
/// <see cref="AnotherClass>is somewhat verbose.</see>
/// </summary>
/// <param name="andSo">is parameter documentation</param>

代わりに、ドキュメントにMarkdownを使用したいと思います。

/// This is text of importance. Linking to [an](OtherClass) is less verbose.
/// 
/// Empty lines would make a new paragraph
///
/// aParameter
/// :    could possibly be documented in definition-list manner
///      as in http://bit.ly/1l9ik26

以前、Stackoverflowでまさにこれに対する質問と回答を見つけたに違いありません。残念ながら、私はもうそれを見つけることができません。私は運がなくて想像できる検索キーワードのすべてのバリエーションを試しました。ですから、皆さんの誰もが重複を見つけてくれることを願っています。少なくとも私の質問は、既存のQ＆Aに異なる表現で「プロキシ」を提供することにより、SOに何らかの価値を追加し、将来の訪問者が自分の情報を見つける可能性を高めます。

更新：

私は最終的に別の検索エンジンを使用して別の質問を見つけたと思います： 自動ドキュメント生成のマークダウン？ 。 DoxygenはMarkdownをサポートしているようです。 DoxygenはC＃もサポートしています。しかし、@ Sam Harwellが言及した要件に関しては、これはおそらく大したことではありません。

c#markdowndocumentation-generationxml-documentation
20
chiccodoro

この要点はかなりうまく機能します： https://Gist.github.com/formix/515d3d11ee7c1c252f92

結果のドキュメントは次のようになります： https://github.com/formix/MegaCityOne/blob/master/MegaCityOne/doc/api.md

5
formixian

理論的には、この例を使用して、C＃プロジェクトに適切なドキュメントファイルを提供できます。ただし、次の理由から、このアプローチは避けることをお勧めします。

  1. Visual Studioは、コメントを直接使用することはできません。作業する前に、適切にフォーマットされたXMLドキュメントファイルを生成するために、Markdownプロセッサを介して実行する必要があります。つまり、referencedプロジェクトについてのみ適切なドキュメントを取得でき、currentプロジェクトについては取得できません。また、XML出力を生成していない場合は、他の開発者がライブラリを参照するときに使用できる出力を生成していません。

  2. RoslynとSHFBプロジェクトはどちらも、XMLドキュメントコメントに対するIntelliSenseサポートの改善に取り組んでいます。現時点では、SHFBはカスタムドキュメントタグの表示に重点を置いています（例：<preliminary/>および<see langword="null"/>）、Roslynは、crefおよびseeタグのseealso属性値のIntelliSenseサポートに焦点を当てています。私の知る限り、C＃コードを文書化する別の方法をサポートするためのプッシュはありません。

4
Sam Harwell

Docfx

https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html

DocFXはAPIドキュメントです。NETのジェネレーター、現在C＃とVBをサポートしています。 APIリファレンスドキュメントを生成しますトリプルスラッシュコメントからソースコードに。また、マークダウンファイルを使用で、チュートリアルやハウツーなどの追加トピックを作成したり、生成されたリファレンスドキュメントをカスタマイズしたりすることもできます。

0
JohnFI

Vsxmdを使用できます（ https://www.nuget.org/packages/vsxmd ）。使用方法の詳細については、パッケージのgithubページをご覧ください（ https://github.com/lijunle/Vsxmd ）

0
Sales Lopes