ndoc2007_使用C＃，NDoc，Lutz的Documentor和Microsoft HTML帮助研讨会的有效XML文档

ndoc2007

A lot has been said on this topic, but here's some stuff you might not know.

关于这个话题已经说了很多，但是这里有些东西你可能不知道。

We use NDoc to document our API.  NDoc consumes the XML Documentation files created as a build artifact by the C# compiler. 

我们使用NDoc来记录我们的API。 NDoc使用C＃编译器创建的XML文档文件作为构建工件。

• Here is the list of recommended XML Documentation tags from Microsoft.

  这是Microsoft推荐的XML Documentation标记的列表。

• Here is the extended list of tags supported by NDoc

  这是NDoc支持的标签的扩展列表

Most links online that talk about XML Documentation in stop at <summary> and the standard <param> stuff.  Method documentation is interesting, but the real meat happens at the top of your Class declarations.  That's where most of the prose is in MSDN documentation.  Take a look at the Remarks section of the Socket Class in the MSDN Help for example. 

关于XML文档的大多数在线链接都以<summary>和标准的<param>开头。 方法文档很有趣，但真正的实质发生在类声明的顶部。 那是大多数散文在MSDN文档中的地方。 例如，请查看MSDN帮助中的Socket类的“备注”部分。

To achieve such a rich structure, organize your XML help thusly on the top of each class declaration:

为了实现这种丰富的结构，因此可以在每个类声明的顶部组织XML帮助：

• <Summary>
  <摘要>

• <Remarks>

  <备注>

  • <Note>(s)
    <注意>

• <Example>(s)

  <示例>

  • <Code>
    <代码>
• <SeeAlso>(s)
  <另请参阅>

The XML Comment snippet below, along with NDoc produced the lovely MSDN-style documentation in the picture at right.

下方的XML Comment片段与NDoc一起在右图中生成了可爱的MSDN样式的文档。

The <summary> tag explains the “point” of the class. A sentence or two is fine here./// <summary>/// Encapsulates Thingie and a Connection to Thingie in a Service wrapper. /// Other Services will be built with this building block. /// </summary>The <remarks> tag is where the real prose goes. Use this tag to describe the general use of the class, as well as any notes, gotchas, or significant design or architectural issues. Note the use of <para> to separate paragraphs. Use <see> to refer to namespaces, classes or methods. If you don’t include the fully qualified namespace, the documenter will assume the current namespace. /// <remarks>/// <para>The ThingieService class contains a <see cref="IConnector"/>/// that is pulled from the named element in the config/ThingieClient.config file. The config file/// is loaded by <see cref="I"/>.</para>/// <para>Note that the constructor is private, as your application gets a ThingieService by calling the static <see cref="GetThingieService"/> method. /// From there, the ThingieService hides the <see cref="IConnector"/> and/// is the primary interface to Thingie. The ThingieService shouldn't be used directly from an ASP.NET/// page. Instead, it should be used from either a generated or hand-written proxy.</para>/// <note type="note">ASP.NET developers should use <see cref="Corillian.Thingie.Security.SiteSecureThing"/> to property register a <see cref="ThingiePrincipal"/> with the system to effectively use the ThingieService.</note>/// <para>There are two ways to call the <see cref="Execute"/> method.</para>/// <list type="bullet">/// <item><term>Pass in an object that implements <see cref="IRequest"/>. /// The Thingie SessionID and UserID will be retrieved from the <see cref="ThingiePrincipal"/> on the current Thread.</term></item>/// <item><term>Pass in an object that implements <see cref="IRequest"/> along with the Thingie SessionID and UserID as additional parameters. /// Use this method if your Thread doesn't already have a ThingiePrincipal. One will be made for you temporarily.</term></item>/// </list>/// </remarks>/// <example>/// <code>/// public class BankingExample/// {/// protected ThingieService thingie = null;/// /// public BankingExample()/// {/// thingie = ThingieService.GetThingieService("BankingServiceProxy");/// }/// /// public virtual SignonResponse Signon(SignonRequest req, string userId, string somethingElse ) /// {/// string sessionid = thingie.SomethingImportantToTheSession(userId); /// string r = thingie.Execute(req, sessionid, userId);/// SignonResponse retVal = SignonResponse.FixUpSomething(r);/// return retVal;/// }/// }/// </code>/// </example>/// <seealso cref="IRequest"/>/// <seealso cref="IConnector"/>/// <seealso cref="IConfig"/>/// <seealso cref="ILoggingService"/> public class ThingieService....

<summary>标记解释了类的“要点”。 这里一两句话就可以了。 /// <summary> ///在服务包装器中封装Thingie和与Thingie的连接。 ///其他服务将使用此构建块构建。 /// </ summary> <remarks>标签是真正的散文去处。 使用此标记来描述类的常规用法以及任何注释，陷阱或重大的设计或体系结构问题。 注意使用<para>分隔段落。 使用<see>来引用名称空间，类或方法。 如果您不包括完全限定的名称空间，则记录器将采用当前的名称空间。 /// <备注> /// < para > ThingieService类包含一个< see cref =“ IConnector” /> ///，它从config / ThingieClient.config文件中的命名元素中提取。 配置文件///由<see cref =“ I” />加载。< / para > /// < para >请注意，构造函数是私有的，因为您的应用程序通过调用静态< see cref = “ GetThingieService” />方法。 ///从那里，ThingieService隐藏<请参阅cref =“ IConnector” />，并且///是Thingie的主要接口。 不应直接在ASP.NET ///页面上使用ThingieService 。 而是应从生成的或手写的代理中使用它。</ para > /// < note type =“ note”> ASP.NET开发人员应使用<请参阅cref =“ Corillian.Thingie.Security.SiteSecureThing” />要向系统属性注册<请参阅cref =“ ThingiePrincipal” />以有效使用ThingieService。</ note > /// < para >有两种方法可以调用<请参阅cref =“ Execute” />方法。</ para > /// < list type =“ bullet”> /// < item > <term>传入实现<的对象<请参见cref =“ IRequest” />。 /// Thingie SessionID和UserID将从当前线程上的<see cref =“ ThingiePrincipal” />中检索。</ term > </ item > /// < item > < term >传递实现的对象<请参阅cref =“ IRequest” />以及Thingie SessionID和UserID作为附加参数。 ///如果您的线程还没有ThingiePrincipal，请使用此方法。 </ term> </ item> /// </ list > /// </备注> /// < example > /// < code > /// public class BankingExample // / { ///受保护的ThingieService物品= null; /// /// public BankingExample() /// { /// thingie = ThingieService.GetThingieService(“ BankingServiceProxy”); ///} /// ///公共虚拟SignonResponse Signon(SignonRequest请求，字符串userId，字符串somethingElse) /// { ///字符串sessionid = Thietie.SomethingImportantToTheSession(userId); ///字符串r = something.Execute(req，sessionid，userId); /// SignonResponse retVal = SignonResponse.FixUpSomething(r); ///返回retVal; ///} ///} /// </ code > /// </ example > /// <see Also cref =“ IRequest” /> /// <seealso cref =“ IConnector” /> /// < seealso cref =“ IConfig” /> /// <seealso cref =“ ILoggingService” />公共类ThingieService...。

I also like to use Lutz Roeder's .NET Documentor to write my XML Comments in.  It has a split-pane view and a nice right-click menu that let's me see what the documentation will look like AS I TYPE.

我还喜欢使用Lutz Roeder的.NET Documentor来编写我的XML注释。它具有一个拆分窗格视图和一个漂亮的右键菜单，让我看看文档的外观如何。

Considering that I'd need to recompile the Application AND generate the MSDN documentation, this little tool is a big time saver.

考虑到我需要重新编译应用程序并生成MSDN文档，因此这个小工具可以节省大量时间。

翻译自: https://www.hanselman.com/blog/effective-xml-document-with-c-ndoc-lutzs-documentor-and-the-microsoft-html-help-workshop

ndoc2007