问题标签 [xml-comments]

有没有一种从 Visual Studio XML 输出生成 MSDN 样式文档的简单方法？
我没有足够的耐心来为它设置一个好的 xslt，因为我知道我不是第一个跨过这座桥的人。

另外，我最近尝试设置沙堡，但它确实让我的眼睛交叉。要么我在这个过程中遗漏了一些重要的东西，要么就是太投入了。

我知道有人有一个非常好的非常简单的解决方案。

我在这里重申，因为我认为我的格式使该段落不宜阅读：

我尝试了沙堡，但设置起来非常困难。我真正想到的是更简单的事情。

也就是说，除非我只是不了解沙堡过程。对我来说，仅仅为测试人员提供一些可以使用的好东西，这似乎是一大堆额外的包袱。

我使用 Visual Studio 中的 LINQ to SQL 设计器来创建数据库的对象模型。现在，我想为每个生成的属性添加 XML 注释，但是如果不删除下次刷新 dbml 文件时的属性，我不知道该怎么做。

如何才能做到这一点？

有人知道 VS 2008 的宏或附加组件可以重新格式化 xml 注释吗？旧版本的 VS 有这个非常聪明的 CommentReflower，但我找不到支持 VS 2008 的版本。

有任何想法吗？提前致谢！

马蒂亚斯

我有一个使用 xml 文档的 VS2008 解决方案，并且在为发布模式打开错误时我们会收到警告（恕我直言，这是一个不错的功能）；然而，这会导致诸如（自我描述）枚举的每个元素之类的“缺少 xml 注释”错误的长列表。

有谁知道一个属性或类似的东西会关闭对 xml 注释的要求？理想情况下，对于某些分隔区域，而不仅仅是一行（否则我可以在每个项目之前放置空标签，有点违背目的......）

谢谢！

在整个 C# 源代码中，我们有很多注释错过了实际内容，例如：

或这个：

或这个：

不幸的是，Visual Studio 不会为这种类型的缺失注释生成警告。但是对我们来说，如果我们可以在 Visual Studio 中单击列表中的一个项目（例如，warings 列表），然后将其带到源代码中的错误位置来纠正它，那就太好了。此外，在每次构建 xml 文件时看到缺少的 xml 注释内容列表也会很高兴。您对如何实现这一目标有任何想法吗？

最近我有点惊讶地发现，我精心设计的 xml 评论并没有在我的同事的智能感知中出现。一直将关联程序集与项目引用一起使用，我没有意识到您还必须导出 .xml 文档才能访问此信息。

这让我想知道 .Net 框架智能感知是如何工作的。如果我理解正确，.xml 文件必须隐藏在特殊文件夹中的某个地方吗？

但我的主要问题是关于“转到定义”——如果你在 .Net 框架程序集上转到定义，你会得到从元数据生成的信息——而且还有很多有用的评论——这些是从 Xml 评论神奇地生成的，还是有人有写一个宏+来转换它们只是为了构建？换一种说法：我怎样才能为我的程序集获得这种效果？

我在 .NET Framework BCL 中的许多类的 XML 注释中看到了这一点，但从未找到解释其作用的文档。

例如，查看 System.Object 会发现以下注释：

您的 .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，但是你要交给另一个团队来维护的代码库呢？

你觉得我应该怎么做？

我以前遇到过几次这种情况。我希望在我的 XML 注释中引用一个类型，但该类型包含在我的项目未引用的程序集中。

在 A.Dll（参考 B.DLL）中：

在 B.DLL 中（不引用 A.DLL）：

在LoserClass我需要参考的评论中，SomeClass但由于 B.DLL 不参考 A.DLL（循环参考），我不能。

是否有某种方法可以将程序集信息包含在LoserClass代码文档中的 cref 中，以便A.SomeClassXML 文档生成器可以解决？

（顺便说一句，你不能总是通过移动类来解决这个问题，因为它会在其他地方导致循环依赖）

早上好，下午，晚上或晚上（取决于您的时区）。

这只是关于 C# 中 XML 注释的一般问题。我从来没有非常热衷于评论我的程序，我一直是一个冗长的变量/属性/方法命名器，让代码自己说话。如果我正在编写相当混乱的代码，我会写评论，但在大多数情况下，我不会写很多评论。

我正在阅读 .NET、Sandcastle 中的 XML 注释和 codeplex 上的帮助文件生成器，它让我走上了想要记录我的代码并为那些必须深入研究我的人生成一些很好、有用的文档的道路。当我不再在这里时的代码。

我的问题是关于标准和约定的。是否有“好的”XML 注释指南？你应该评论每一个变量和属性吗？每种方法？我基本上只是在寻找有关如何编写好的注释的提示，这些注释将由 sandcastle 编译成好的文档，这样其他程序员在最终不得不处理我的代码时就不会诅咒我的名字。

提前感谢您的意见和建议，Scott Vercuski