问题标签 [ndoc]

我正在使用 D2007 并尝试使用 HelpInsight 功能（自 D2005 起提供）记录我的源代码。我主要对让 HelpInsight 工具提示正常工作感兴趣。从各种网上冲浪和实验中，我发现了以下内容：

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

尽管遵循这些“规则”，但有时 Help-insight 只是找不到我写的评论。一个文件不会产生正确的 HelpInsight 工具提示，但如果我将此文件包含在不同的虚拟项目中，它就可以正常工作。

有没有人有其他让 HelpInsight 工作的指示/技巧？

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

一些背景：我继承了我在 SO 上发布的其他一些问题中谈到的大型代码库。该代码库的“特性”之一是 God Class，它是一个具有超过 3000 行代码的单个静态类，包含几十个静态方法。这是从Utilities.CalculateFYBasedOnMonth()到Utilities.GetSharePointUserInfo()到的一切Utilities.IsUserIE6()。这都是不需要重写的好代码，只需重构为一组适当的库。我已经计划好了。

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

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

这些示例来自 Document X 示例：

和：

所以我想问您：您是否使用 XML 注释来记录您的所有代码，目的是使用 NDoc (RIP) 或 Sandcastle 之类的东西？如果没有，您如何决定哪些获取文档，哪些不获取？像 API 之类的东西显然会有 doco，但是你要交给另一个团队来维护的代码库呢？

你觉得我应该怎么做？

NDoc 有一个 XML 元素inheritdoc，它允许您从父类（或实现的接口）继承成员的文档。然而，Visual Studio（即 C# 编译器）不理解这个标签并抱怨文档不存在或不完整。StyleCop 和其他一些工具也是如此。有替代方法吗？您如何在不重复 XML 描述的情况下保持文档的完整性？

我已经使用 NDoc 很长一段时间了，现在使用 NDoc 增强版（ http://sourceforge.net/projects/ndoc-e/ ）的自定义构建（即稍微修复错误的构建），但我遇到了一个奇怪的问题使用具有参数的方法，这些参数本身采用通用参数。

例如，任何具有 Dictionary 作为参数的参数，其中字典的类型参数不是基类类型，都无法正确找到文档，因为当代码使用 Type.FullName 获取类型时，它会得到一个非常长的字符串，如下所示：

我想一定有办法解决这个问题，但我不知道是什么。真正奇怪的是，具有上述全名的类型将报告自己不是 GenericType 或具有 GenericTypeParameters，这对我来说似乎完全错误。有谁知道这是什么问题和相应的解决方法？

我可以改用没有此问题的 NDoc3，但该项目未发布其源代码，因此我无法自己查找。

有人可以满足我的好奇心并启发我吗？

微软在发布 Sandcastle 的 CTP/Beta 版本时杀死了 NDoc，我很少看到有关可用版本 Sandcastle 的新版本的信息（例如，带有集成 UI）。最新版本是 2008 年 5 月的版本。Sandcastle 是死项目还是会包含在 Visual Studio 2010 中？

我正在使用 NDOC3 编写项目文档。

尝试记录第 3 方 DLL 时构建失败（因为我没有它们的 xml 文档）。我该如何解决这个问题？

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

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

我发现自己在看 .NET 框架评论说什么，但这很快就过时了；如果我可以有一些好的规则来指导自己，我可以更快地完成我的文档。

给定一个类的 XML 注释，如下所示：

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

使用 .NET Framework 3.5，我有 nant -0.91-alpha2，它支持 framework 3.5，但是当我尝试构建文档时出现以下错误。

该文档将由以下内容生成：

我的项目经理上周暗示在类中的属性上使用 ndoc。这是应该做的事情吗？这样做是否被认为是最佳实践？我目前正在为我正在处理的项目部分扩展我的所有 ndoc，但不知道我需要多深。我当然已经为类和每个方法提供了摘要、参数、返回和备注，但是属性也需要 ndoc 吗？