标签: ndoc

NDoc有一个XML元素inheritdoc,它允许您从父类(或实现的接口)继承成员的文档.但是,Visual Studio(即C#编译器)不理解此标记并抱怨文档不存在或完整.StyleCop和其他一些工具也是如此.有替代方法吗？你如何保持文档完整,但没有重复XML描述？

我正在编写一些我刚编写的新代码,并将NDoc sytle注释添加到我的类和方法中.我希望生成一个非常好的MSDN样式文档供参考.

一般来说,在为类和方法编写注释时,有哪些好的指导原则？NDoc评论应该说什么？他们应该怎么说？

我发现自己正在研究.NET框架评论所说的内容,但这种情况会变得很快; 如果我能有一些好的规则来指导自己,我可以更快地完成我的文档.

微软在发布Sandcastle的CTP/Beta版本时杀死了NDoc,我很少看到有关沙堡的可用版本的新版本的信息(例如,带有集成的UI).最新的发布是2008年5月的发布.Sandcastle是一个死的项目还是将它包含在Visual Studio 2010中？

给出类似于这样的类的XML注释:

///<summary>Handles the AuthenticateRequest event in the ASP.NET page request lifecycle to authenticate users.</summary>
///<remarks>
///<para>This module will authenticate users based on cookies, form posts, or an impersonation request from the  admin system.</para>
///<para>If authentication succeeds, both the <see cref="System.Threading.Thread.CurrentPrincipal" /> and the <see cref="System.Web.HttpContext.User"/> property are set to an instance of <see cref="MyPrincipal"/> representing the authenticated user.</para>
///</remarks>

如何获取对框架文档中相应页面的引用System.Threading.Thread.CurrentPrincipal和System.Web.HttpContext.User链接？

我正在使用D2007并尝试​​使用HelpInsight功能(自D2005以来提供)来记录我的源代码.我主要想让HelpInsight工具提示工作.通过各种网络冲浪和实验,我发现了以下内容:

1. 使用三斜杠(///)注释样式比其他记录的注释样式更常用.即: {*! comment *}和{! comment }
2. 评论必须在它们所针对的声明之前.对于大多数情况,这将意味着将它们放在代码的接口部分.(明显的例外是对于无法从当前单元外部访问的类型和函数,因此在实现块中声明.)
3. 第一条评论不能用于函数.(即它必须是一个类型 - 或者至少看起来解析器必须在HelpInsight功能工作之前看到"type"关键字)

尽管遵循了这些"规则",但有时帮助洞察力却找不到我写的评论.一个文件没有生成正确的HelpInsight工具提示,但如果我将此文件包含在一个不同的虚拟项目中,它可以正常工作.

有没有人有任何其他指针/技巧让HelpInsight工作？

您的.NET源代码文档中有多少是太多了？

一些背景:我继承了一个很大的代码库,我已经在SO上发布了一些其他问题.这个代码库的一个"特性"是God Class,一个包含大约3000行代码的单个静态类,包含几十个静态方法.这是一个从一切Utilities.CalculateFYBasedOnMonth()要Utilities.GetSharePointUserInfo()到Utilities.IsUserIE6().这些都是不需要重写的好代码,只需重构成一组适当的库.我已经计划好了.

由于这些方法正在进入一个新的业务层,我在这个项目中的角色是为其他开发人员准备系统以进行维护,我正在考虑可靠的代码文档.虽然这些方法都具有良好的内联注释,但它们并不都具有XML注释形式的良好(或任何)代码doco.使用GhostDoc和Sandcastle(或文档X)的组合,我可以创建一些非常好的HTML文档并将其发布到SharePoint,这将使开发人员更多地了解代码的作用,而无需浏览代码本身.

随着代码中文档量的增加,导航代码变得越困难.我开始怀疑XML注释是否会使代码更难以维护,比如说//comment每个方法更简单.

这些示例来自Document X示例:

        /// <summary>
        /// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
        /// </summary>
        /// <returns>A new Customer instance that represents the new customer.</returns>
        /// <example>
        ///     The following example demonstrates adding a new customer to the customers
        ///     collection. 
        ///     <code lang="CS" title="Example">
        /// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
        ///     </code>
        ///     <code lang="VB" title="Example">
        /// Dim newCustomer As CustomersLibrary.Customer …