解釋說明VS XML注釋插件常見問題
雖然有許多人對VS XML注釋的插件表示懷疑,但在年復一年的不斷發展中,他的插件問題也在不斷提高。保障VS XML注釋的插件穩定運行是完全有可能的,但前提是要深入理解到底什么是VS XML注釋,及他是怎么運作的。
這些手工標記是非常有用的,如果恰當地設置他們,對導出成外部說明文件將非常有幫助。如果碰到是預先定義的xml標記,編譯器可以把這些注釋以文本輸出;如果是編譯器不認識的xml標記,編譯器會逐字的把所有內容都輸出,這意味著你可以使用自己定義的標記。#t#
適當的設置,C#編譯器并不格式化VS XML注釋,而是以xml文件輸出。下面的步驟將演示如何讓C#編譯器把VS XML注釋輸出為xml文件。右鍵點擊解決方案資源管理器中的工程項,打開工程的屬性頁,點擊屬性。對話框出現后,點擊配置屬性目錄。點擊生成節點。
在右邊的框中有輸出--xml文檔文件,這里就是設置叢VS XML注釋生成xml文件的文件名。(注:這里設置的是相對路徑,不是絕對路徑)。在我的例子中,我使用GiveHelpDoc.xml作為文檔名,如果這里沒有輸入任何值,這將是默認設置。
公認的標記我把VS XML注釋標記分類兩大類:***類是設置標記,我叫他們主標記。他們在一組標記的開始,而且不會在標記內部出現。第二類是設置標記包含的標記,我叫他們支持標記。支持標記和html標記的區別在于:支持標記采用的是小寫,html標記采用的是大寫,顯示了我將要討論的支持標記和主標記。
GiveHelpTransforms.cs部分代碼:
- namespace GiveHelp
- {
- <remarks>
- Class that contains functions to do transformations to help files.
- The source XML is loaded into the <see cref="SourceXML"/> property
- (e.g. <c><I>obj</I>.SourceXML = "<I>XML goes here</I>"</c>). One of
- the associated member functions (<see cref="GiveTypeListHTMLHelp"/
- >, <see cref="GiveMemberListHTMLHelp"/>, <see
- cref="GiveMemberHTMLHelp"/>)
- is called to initiate and then return the transformation.
- <para>
- <list type="table">
- <listheader>
- <term>Help Page</term>
- <description>Function to call</description>
- </listheader>
- <item><term>List of Types</term>
- <description>GiveTypeListHTMLHelp</description></item>
- <item><term>List of members</term>
- <description>GiveMemberListHTMLHelp</description></item>
- <item><term>Help for a single member</term>
- <description>GiveMemberHTMLHelp</description></item>
- </list>
- </para>
- </remarks>
- <permission cref="">public</permission>
- <example><code>
- // create the class that does translations
- GiveHelpTransforms ght = new GiveHelpTransforms();
- // have it load our XML into the SourceXML property
- ght.LoadXMLFromFile("E:\\Inetpub\\www-
- root\\GiveHelp\\GiveHelpDoc.xml");
- // do the translation and then write out the string
- Response.Write( ght.
- GiveMemberHTMLHelp(Request.QueryString.Get("Type"),
- Request.QueryString.Get("Member")) );
- </code></example>
- public class GiveHelpTransforms
- {