.Net Core 如果没有 xml 评论,文档是如何构建的

.Net Core How is the documentation built if not with xml comments

我使用 Sandcastle 有一段时间了,我也习惯于在 .Net 源参考中查找 xml 内联注释。它们通常与 msdn 上的描述完全匹配。
自从 .Net 4.6 和 .Net Core 以来,微软似乎以不同的方式创建了他们的评论。
(再也无法在 .Net 源参考中找到它们)

例子:
https://msdn.microsoft.com/de-de/library/system.string.padright(v=vs.110).aspx
此方法在 msdn 中有注释,但我无法在源代码中找到它:
http://referencesource.microsoft.com/#mscorlib/system/string.cs,56cb688f4f1dc9e4

我想知道他们现在如何使用 .Net 4.6 以及他们如何 will/are 使用 .NET Core 来做到这一点。 任何人都可以确认并向我解释一下吗?

编辑: 由于 .Net Core 是开源的,我们应该能够解决这个问题。但是我找不到任何相关信息。

EDIT2:由于 .Net Core 是开源的,我认为我们应该可以访问或至少能够访问他们的内部 "secret" 文档工具。我们还能如何进一步开发 .Net Core 并编写文档。 有人知道该工具或在哪里可以找到它吗?

Microsoft 似乎将评论保存在单独的文件中,并且与他们在构建 MSDN 和本地化方面的内部工作流程很好地集成在一起。 Sandcastle曾经是一个主要使用的工具,后来开源了,

https://sandcastle.codeplex.com/

Sandcastle 由于其复杂性和 .NET Framework 中后来的变化而被放弃。

CoreFX 存储库 GitHub 上已经有一个线程将此类评论移回 C# 源文件,但由于时间紧迫,不会很快发生,

https://github.com/dotnet/corefx/issues/230 https://github.com/dotnet/corefx/issues/6518

罗斯林方面可能还有一些其他变化,

https://github.com/dotnet/roslyn/issues/85

.NET Core 的当前文档是使用 DocFX 构建的,

https://dotnet.github.io/api/

它也在 GitHub 上开源,它应该仍然从内部文件中获取评论,

https://github.com/dotnet/docfx

让我们看看接下来几个月的情况。

旁注是Xamarin有自己的文档解决方案,只有BCL部分来自微软,

http://www.zdnet.com/article/microsofts-open-sourcing-of-net-the-back-story/

遗憾的是,什么系统生成 .NET Framework 4.* 的当前 MSDN 文档是未知的。

免责声明 MSDN 工程团队的开发人员,同时维护旧平台和新平台。

首先,我们确实为 MSDN 生成了多个文档 tools/solution,但核心部分始终是反射。我们利用自动工具帮助从源代码中提取 API 签名和评论,然后将它们保存在 XML 或 Markdown 文件中。我们使用的最新工具是 DocFX http://dotnet.github.io/docfx/.

其次,由于所有 API 签名和评论都存储在文件中,技术作家正在 able/allowed 修改它们以使其更具可读性(现在我们在源代码和最终产品之间存在差距, 正确的?)。此外,作者将添加单独的文件,即概念文档,以填写相应的描述、代码示例和指南 API。

最后,所有这些文件都将转换为 xliff 文件以进行本地化。

简而言之,这些文档是根据源代码注释和作者的输入生成的。后面的将在稍后移至 GitHub,欢迎社区贡献。