2016-04-08 38 views
4

我正在使用Sandcastle一段時間,而且我也用於在.Net源參考中查找xml內聯註釋。它們通常與msdn上的描述完全匹配。
由於.Net 4.6和.Net核心,它似乎像微軟創建他們的評論不同。
(不能在.NET源參考找到它們了)

.Net Core如果不使用xml註釋創建文檔如何不使用xml註釋

一個例子:
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核心是開源的,我們應該能夠弄清楚這一點。但我找不到任何有關它的信息。

EDIT2:由於.Net Core是開源的,我認爲我們應該有權訪問或至少能夠訪問他們內部的「祕密」文檔工具。我們還可以如何進一步開發.Net Core並編寫文檔。 有誰知道該工具或在哪裏可以找到它?

+0

對於.Net Core沒有內部的「祕密」文檔工具,它只是DocFX。 – Rebornix

回答

11

免責聲明 MSDN工程團隊的開發人員,維護傳統平臺和新平臺。

首先,我們確實爲MSDN提供了多種文檔生成工具/解決方案,但核心部分始終是反射。我們利用自動工具幫助從源代碼中提取API簽名和評論,然後將它們保存在XML或Markdown文件中。我們正在使用的最新工具是DocFX http://dotnet.github.io/docfx/。其次,由於所有API簽名和註釋都存儲在文件中,因此技術編寫者可以/允許對其進行修改以使其更具可讀性(現在我們在源代碼和最終產品之間存在差距,對不對?)。此外,作家將添加單獨的文件,即概念文件,以填寫描述,代碼示例和指導到相應的API。

最後,所有這些文件將被轉換爲xliff文件進行本地化。

簡而言之,這些文檔是從源代碼評論和作者的輸入生成的。後面的一個將在稍後轉移到GitHub上,歡迎社區貢獻。

+1

你能介紹一下嗎?我一直在玩DocFX,從代碼註釋生成API文檔並添加概念內容。但是,我沒有看到一個清晰的路徑來生成翻譯人員可以使用的XLIFF文件,並且能夠將其轉換回本地化的Web內容。更令人擔憂的是,如果在XLIFF中更改了源註釋(en-US),或者源代碼更改爲添加或刪除字段,方法,類等時,我無法看到所有內容都可以保持同步。 –

2

微軟似乎將註釋保存在單獨的文件中,並且與構建MSDN和本地化的內部工作流程很好地結合在一起。沙堡曾經使用的主要工具,但後來做開源,

https://sandcastle.codeplex.com/

沙堡已被放棄,由於其複雜性和.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核心目前的文檔是使用內置文件FX,

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文檔不明。