.Net Core如果没有xml注释,如何构建文档

Question

我现在正在使用Sandcastle一段时间,我也习惯在.Net Source Reference中找到xml内联注释.它们通常与msdn上的描述完全匹配.
从.Net 4.6和.Net Core开始,似乎微软以不同的方式创建了他们的评论.
(不能再在.Net Source Reference中找到它们)

一个例子:
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以及他们将如何/正在使用.NET Core.任何人都可以向我确认并解释这个吗？

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

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

Answer 1

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

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

其次,由于所有API签名和注释都存储在文件中,技术编写者可以/允许修改它们以使它们更具可读性(现在我们在源代码和最终产品之间存在差距,对吗？).此外,作者将添加单独的文件,即概念文档,以填写描述,代码示例和相应API的指导.

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

简而言之,这些文档是根据源代码注释和编写者的输入生成的.稍后将会转移到GitHub并欢迎社区贡献.

Answer 2

Microsoft 似乎将注释保存在单独的文件中，并且与构建 MSDN 和本地化的内部工作流程很好地集成。Sandcastle曾经是主要使用的工具，但后来开源了，

https://sandcastle.codeplex.com/

Sandcastle 由于其复杂性以及 .NET Framework 的后续变化而被放弃。

GitHub 上的 CoreFX 存储库上已经有一个线程将此类评论移回 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-source-of-net-the-back-story/

不幸的是，什么系统生成 .NET Framework 4.* 的当前 MSDN 文档尚不清楚。