问题标签 [xml-documentation]

我正在使用 GhostDoc 来记录我的方法等......并且它运行良好，但它并没有填补<returns>......

谁能告诉我我应该做什么，即

如果它返回一个名为“角色”的对象，那么

或者干脆

或者

我知道它的声音有点太精确了，但我想从正确的开始:-)

以用户名的标准字符串返回类型为例

可能重复：
如何在 xml 文档中引用泛型类和方法

我一直在使用 see cref 标记，它工作得很好，但现在我需要在 see cref 中包含一个字符串 [] 的通用列表，但文档没有正确呈现。

我认为它与 < 和 > 以及 [] 有关

这是否允许，有解决方法吗？

当前的体系结构基于 WCF 服务，这些服务从 DB 填充 DTO 对象并返回它们。

有些方法返回完整的对象图，有些只返回部分。如果完全填充，一些对象图会非常大 - 所以这不是所有情况的选择。

如何记录 DTO 对象的哪些属性已填充，哪些未填充？这是一个 .NET 商店，并且 XML 注释没有提供足够的灵活性来记录不总是填充的属性。其他人如何应对这一挑战？

例如：对于客户来说，Invoice 对象是相同的，无论它是否填充了所有属性。

提出的一个想法是为仅具有填充属性的对象生成 XSD 模式。尽管在技术上是正确的，但这似乎不是一个“好/可用”的文档。

编辑：我发现 UML 可能是比 XSD 更好的选择，因为它更具可读性。有没有从 XML -> XSD -> UML（或其他图表范例）快速的方法？

对于编写摘要和参数文本，是否有最佳实践来说明您必须了解多少细节，是否使用完整的句子或其他什么？我只是在寻找一些好习惯来建立，因为我开始更多地使用这些习惯。谢谢！

我有这个功能：

我要记录的。
我想让<return>标签告诉string.Join(separator, strings.ToArray())任何能够阅读 C# 代码的人，这会说一千多个单词。但是，当我使用

然后 string.Join(separator, strings.ToArray()) 将被格式化为纯文本，这使得它几乎不可读。所以我尝试了

但这总是会创建一个新段落...

所以这是我的问题：
有没有办法格式化一段文本，让它看起来好像是代码？我会对固定宽度的字体感到满意。

我非常喜欢.NET中的 XML 文档。

但是，老实说，我从来没有见过一个教程或项目，例如，我们有这样的标记：

代替：

这有什么特别的原因吗？我是唯一一个想要记录我的控制器方法的人吗？

编辑1：

虽然大多数控制器方法似乎很简单，但在说这个问题中详细说明的情况如何：MVC：如何使用具有许多子实体的实体？?

我正在 VS 2005 下用 C# 编写一个类库（我知道，与现代同步，但我们这里的预算很紧）。

在我看来，如果我在 XML 文档中使用“摘要”标签，我的用户可以通过 Intellisense 和工具提示等查看该信息，但不能在 Studio 的“属性”窗口中查看。

为了在那个窗口中得到一些东西，我似乎需要使用一个[Description("This is it")]属性。

我对此是否正确？如果是这样，那么我似乎需要复制描述信息:-(

或者，还有更好的方法？谢谢！

虽然我认为我理解为什么内联 XML 文档（即使用三个斜杠 - ///）对我不起作用，但我想获得一些关于如何解决我的“问题”的指导。

我有一个接口和两个派生类。一个派生类用于模拟，另一个用于与真实硬件对话。

硬件实现很可能会做一些模拟器不需要做的特殊事情。我有硬件方法的 XML 文档，而不是模拟器。但是，当我将鼠标悬停在方法名称上时，我根本没有在工具提示中获得文档，大概是因为 XML 文档与接口没有关联。

这当然是有道理的，我打算只将我的文档放在界面中并使用它。不过，我仍然很好奇……其他人是怎么做到的？有什么神奇的方法可以让工具提示聚合所有有效的 XML 文档吗？换句话说，由于编译器不知道正在使用哪个派生类，有没有办法为实现该接口的所有类显示 XML 文档？

我需要将 XML 文档从基类传播到派生类或从接口传播到实现。

我可以使用 Resharper 做到这一点吗？

如果您键入“///”，VS2010 会插入一个 xml-doc 块。但是，似乎没有办法自定义插入的 xml-doc 模板。我只找到了一种适用于 VB.NET 或使用 GhostDoc 等外部工具的方法。

有没有办法在没有外部工具的情况下做到这一点？