.Net Core Как создается документация, если не с комментариями xml

Question

Я работаю с Sandcastle некоторое время, и я также использую для поиска встроенных комментариев xml в исходной ссылке .Net. Они обычно соответствуют именно описаниям, найденным в msdn.
С .Net 4.6 и .Net Core кажется, что Microsoft создает свои комментарии по-разному.
(Не можете найти их в .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. Может ли кто-нибудь подтвердить и объяснить это мне?

EDIT: Поскольку .Net Core - это Open Source, мы должны это понять. Но я не могу найти никакой информации об этом.

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.

Существует уже нить на 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 Ядра построен с использованием док FX,

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

который также является открытым исходным кодом на GitHub, который должен захватить комментарии еще из внутренних файлов,

https://github.com/dotnet/docfx

Давайте посмотрим, как идут дела в ближайшие несколько месяцев.

Sidenote что Xamarin имеет свое собственное решение документации и только BCL часть поступает от Microsoft,

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

К сожалению, что система генерирует текущую документацию MSDN для .NET Framework 4. * неизвестен ,