问题标签 [xml-documentation]

<see cref="switch" />，例如，不起作用 - 我收到编译警告：XML comment on ... has syntactically incorrect cref attribute 'switch'

有兴趣的人的上下文...

有问题的标签可以在<remarks>标签中找到SerializeProperty。我在冗长的文档方面犯了错误。我还计划提供一些<example>s，我只是还没有开始。

好奇的问题。我正在使用 Microsoft 的 Sandcastle 从我的 C# 代码中的 XML 注释生成文档。我的几个类正在实现已经有注释方法的接口。我宁愿不要在接口方法和公共实现方法中复制文档。我可以使用某种标签从界面“继承”此文档吗？

我正在使用XML Documentation Comments记录一个程序集，将使用Sandcastle从该程序集创建一个chm文件。

我的程序集包含各种接口，每个接口都由一个类实现（在我的场景中，这些是 WCF 服务）。

我已经在接口中添加了文档，有什么方法可以自动记录实现类的相关方法吗？

我有这门课，你在下面的答案中看到。在那里我可以参考例如Valuewith<see cref="Value"/>和类本身 with <see cref="GenericEventArgs{T}"/>。

1. 我如何引用默认值（T）？甚至可能吗？
2. 如何引用构造函数？

我一直在尝试使用 XML 注释来完整记录类库的所有类型、方法、属性等，但遇到了涉及cref属性的奇怪效果（see例如，由标签使用）。按照这个 MSDN 页面的建议以及 MSDN 和其他网站上的各种其他示例，似乎每当使用cref标签指定参考值时，它必须以某个标记为前缀，该标记对参考进行分类（例如 ' T:' 表示类型，'M:' 表示方法）。

但是，使用 Microsoft Sandcastle 时，我观察到缺少这些前缀会影响生成的文档（在这种情况下为 CHM 帮助文件）。包括前缀（在我相信的所有情况下），引用在页面上呈现为粗体文本......但不包括前缀，引用被呈现为 API 参考中相应页面的锚（链接）。对我来说似乎很奇怪，推荐的前缀（全部？）引用方法给出的结果最不有用 - 为什么引用在一种情况下呈现为粗体并在另一种情况下链接？如果有人能对此有所了解，我将不胜感激。

你会为命名空间编写 xml-doc 吗？如果是，如何以及在哪里？

我想，如果可能的话，可能是一个几乎是空的文件，如下所示：

但这会奏效吗？既然你......“声明”，或者至少在所有其他文件中使用命名空间......如果你在同一个命名空间的其他地方写了一个 xml 文档会发生什么？一个会消失吗？或者它们会以某种方式合并？

是否有自动方法在接口及其实现之间同步注释？我目前正在记录它们，并且不想手动使它们保持同步。

更新：

考虑这段代码：

当我这样创建类时：

这里没有显示评论：

该<inheritDoc/>标签将完美地在 Sand Castle 中生成文档，但在智能感知工具提示中不起作用。

请分享你的想法。

谢谢。

我想知道是否可以在评论中引用动态泛型类名并在 IDE 中有条件地解决它？

简单的基类示例：

如果我现在从此类继承并且恰好是User类，那么我希望 IntelliSense 将我的评论显示为“从数据库中检索所有用户成员”。

这可能吗？

这个问题类似于Getting Emacs fill-paragraph to play nice with javadoc-like comments，但适用于 C#。

我有这样的评论：

我希望 fill-paragraph仅填充 text，并将标记元素保留在它们自己的单独行上，例如，

我认为我需要设置段落开始变量。Ch v 告诉我它的当前值是：

...这已经看起来很毛茸茸了。（我讨厌 emacs 正则表达式的所有转义 reqd。）我想我需要回顾一下XML doc 元素（如 <remarks>）之后的第一行开始一个段落。

我现在要搞砸了，但是有没有人设置它来做内联代码文档？

编辑：哎呀！Emacs 正则表达式不会向后看！好的，还有其他建议吗？如何将段落的开头设置为 <summary> 或 <para> 之后的行？

ps：我上面示例中的假代码文档来自对美国独立宣言的古腾堡副本的马尔可夫链操作；感谢这个问题的技术。

我的 Visual Studio 解决方案包括一个 Web 应用程序和一个单元测试应用程序。我的网络应用程序使用 log4net。我希望能够从命令行使用 msbuild 来构建我的解决方案。但是，每当我从命令行构建解决方案时，都会出现构建错误，因为它无法将 log4net.xml 复制到测试项目的 bin 目录。

错误信息是：

“无法将文件 '\bin\log4net.xml' 复制到 'bin\Debug\log4net.xml'。对路径 '\bin\log4net.xml' 的访问被拒绝。”

看起来 Visual Studio 正在锁定这个文件，但我不知道为什么需要它。有没有办法防止 VS 锁定它已加载的项目中的 XML 文档文件？