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

Question

I am working with Sandcastle for a while now and I am also used to find xml inline comments in the .Net Source Reference. They usually match exactly the descriptions found on msdn.
Since .Net 4.6 and .Net Core it seems like Microsoft creates their comments differently.
(Cannot find them in the .Net Source Reference anymore)

An example:
https://msdn.microsoft.com/de-de/library/system.string.padright(v=vs.110).aspx
This method has a comment in msdn but I am not able to find it in the source:
http://referencesource.microsoft.com/#mscorlib/system/string.cs,56cb688f4f1dc9e4

I am wondering how they are doing it right now with .Net 4.6 and how they will/are doing it with .NET Core. Can anyone confirm and explain this to me?

EDIT: Since .Net Core is Open Source we should be able to figure this out. But I cannot find any information about it.

EDIT2: Since .Net Core is Open Source I think we should have access or at least be able to get access to their internal "secret" documentation tool. How else can we further develop the .Net Core and write documentation. Does anyone know that tool or where to find it?

Answer 1

Disclaimer Developer of MSDN engineering team, maintain both the legacy platform and the new one.

Firstly, we do have multiple document generation tools/solution for MSDN, but the core part is reflection, always. We leverage automatic tools to help extract API signatures and comments from source code, then save them in XML or Markdown files. The latest tool we are using is DocFX http://dotnet.github.io/docfx/.

Secondly, as all the API signatures and comments are stored in files, technical writers are able/allowed to modify them to make them more readable (now we have gap between source code and final product, right?). Besides, writers will add separate files, aka Conceptual Documents, to fill in description, code samples and guidance to corresponding API.

Lastly, all these files will be converted to xliff files for localization.

So in short, these documents are generated from source code comments and writers' input. The later one will be moved to GitHub later on and community contributions are welcome.

Answer 2

Microsoft seems to keep comments in separate files and that integrates well with their internal workflow on building MSDN and localization. Sandcastle was once a main tool used, but later made open source,

https://sandcastle.codeplex.com/

Sandcastle has been abandoned due to its complexity and the later changes in .NET Framework.

There is already a thread on CoreFX repo at GitHub to move such comments back to the C# source files but due to the tight schedule it won't happen very soon,

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

And there might be some other changes on Roslyn side,

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

The current documentation for .NET Core is built using DocFX,

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

which is also open source at GitHub, which should grab the comments still from the internal files,

https://github.com/dotnet/docfx

Let's see how things go in the next few months.

A sidenote is that Xamarin has its own documentation solution, and only the BCL part comes from Microsoft,

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

Unfortunately what system generates the current MSDN documentation for .NET Framework 4.* is unknown.