问题标签 [sandcastle]

用于生成 API 文档的工具是否有一种标准方式来处理部分类的 XML 样式注释？基本上，一个人应该如何评论一个部分类/方法，以便生成的帮助文档不会被破坏？这个问题可能因使用的工具而异，在这种情况下，我猜最重要的两个工具是：

• Visual Studio 的内置方法来创建 XML 文档
• 微软的沙堡

我不希望我的 XML 文档变得时髦

基本上，何时真正需要（如果有的话）使用完全限定的 xml，请参阅参考：

此外，如何引用 .NET Framework 对象？

我了解完全合格的项目将始终允许 Microsoft 的 Sandcastle 正确链接事物，但是是否有必要使所有内容都完全合格？

旁注：Microsoft Sandcastle 是否能够链接到 .NET Framework 帮助文件，或者我是否通过引用来浪费时间<see cref="T:System.Collections.Generic.ICollection{T}"/>？

我知道，如果您///在类、字段、方法或属性之上，Visual Studio 将开始为您建立 XML 样式的注释。

但是，我在哪里可以为我的命名空间和/或库添加 XML 注释...

例如：

• .NET 框架类库
  • System.Collections 命名空间
    1. System.Collections 命名空间
    2. System.Collections.Concurrent 命名空间
    3. ...

我不确定这些页面是手动创建的，还是通过在适当位置添加的 XML 样式注释自动创建的？

可能重复：
如何在 C# 中的 <seealso> 标记中为方法重载创建 cref？

如何对我的代码进行 XML 注释，以便我指向类似的内容而不是每个单独的方法？计算哈希重载

基本上，您输入什么，cref以便它引用类似于 MSDN 的方法重载页面？

我正在使用 Sandcastle 帮助文件生成器，并希望在“概念内容”中包含彩色 HTML 代码片段。这可能吗？如果可以，怎么做？

我尝试过 <code>、<codeExample> 和 <sampleCode language="HTML" />。

到目前为止，最好的结果是对示例 HTML 进行 HTML 编码，并将其放在 .snippets 文件中，如下所示。

然后在 .aml 文件中引用它。

我更希望将其着色，但我无法找到添加格式的方法。

如果一个类实现了接口中定义的方法，您可以选择是复制文档还是使用<see cref="..." />.

是否可以让 API 文档工具（Sandcastle）自动复制文档（怎样才能让阅读 API 文档更舒服）？类似于@inheritDocJava Doc 的东西？

I have an open-source project (here) whose documentation is currently in French. The documentation is generated from XML comments in code, using Sandcastle. Now I would like to translate the documentation to English and provide documentation in both languages, but I don't really know where to start...

• Do I need to extract the XML comments from the code and put them in a separate file? If yes, are there any tools to automate the process?
• I'm using Sandcastle Help File Builder to build the documentation; do I need to create a separate project to build the doc in English, or can it be done from the same project?
• Are there any tools to help in the translation process? e.g. display the original and translated doc side by side?

I'm also interested in links on how to produce multilingual documentation, as I couldn't find anything useful on Google...

好吧，我有一个带有几个类的程序集和一个带有几个方法的接口

现在，当我在此程序集上运行 SandCastle 时，它​​会生成应有的文档，但是如果我转到接口上的方法，它不会像处理参数那样记录返回类型。

我的猜测是样式文件或某些东西有问题，但我不知道要编辑哪个文件，所以我错过了什么？

更新：

我正在使用

• Sandcastle 帮助文件生成器实用程序，版本 1.9.3.0
• Sandcastle - 2010 年 6 月发布（版本 2.6.1062.1）
• 沙堡风格 2010 年 6 月 (2.6.10621.1) - 修订版 1

好吧，标题问了一切。

我有 Sandcastle 帮助文件生成器 GUI。我可以生成帮助文件，但我想知道除了重新编译整个帮助文件之外，是否有更快的方法来查看结果。

我询问了 Sandcastle，因为我尝试过的其他提供预览功能的工具不会像 Sandcastle 那样将帮助文件编译成确切的规范。他们中的大多数都需要完全合格的参考资料，这很麻烦。

我正在从 nDoc 迁移到 Sand Castle 以生成文档以供我的班级参考。nDoc 不支持 .net 2.0 并且有许多其他限制。

早些时候，使用 nDoc，我能够为我的代码应用漂亮的颜色，包括突出显示类名。

例如Console.WriteLine(something)会Console以不同的颜色显示（因为 nDoc 允许您直接在 XML 中指定 HTML 样式）。

但是，Sand Castle (MAML) 似乎忽略了类型名称（它只接受真正的 C# 代码，不允许用于着色的 HTML 属性，着色由 Sand Castle 本身执行）。最后，只有关键字、注释和常量被着色。这可以修复，以便类型名称也可以着色吗？谢谢！

以下是我使用 nDoc 所拥有的内容以及我需要使用 Sand Castle 复制的内容（MailMessage，Pop3并Console突出显示）。