展现C#世界之九：配置和调度

　　清单9.6 为文档添加一个备注和bullet list

　　1： using System；

　　2： using System.Net；

　　3： using System.IO；

　　4： using System.Text；

　　5：

　　6： /// <summary>Class to tear a Webpage from a Webserver</summary>

　　7： /// <remarks>The class RequestWebPage provides：

　　8： /// <para>Methods：

　　9： /// <list type="bullet">

　　10： /// <item>Constructor

　　11： /// <see cref="RequestWebPage（）"/> or

　　12： /// <see cref="RequestWebPage（string）"/>

　　13： /// </item>

　　14： /// </list>

　　15： /// </para>

　　16： /// <para>Properties：

　　17： /// <list type="bullet">

　　18： /// <item>

　　19： /// <see cref="URL"/>

　　20： /// </item>

　　21： /// </list>

　　22： /// </para>

　　23： /// </remarks>

　　24： public class RequestWebPage

　　25： {

　　26： private const int BUFFER_SIZE = 128；

　　27：

　　28： /// <summary>m_strURL stores the URL of the Webpage</summary>

　　29： private string m_strURL；

　　30：

　　31： /// <summary>RequestWebPage（） is the constructor for the class

　　32： /// <see cref="RequestWebPage"/> when called without arguments.</summary>

　　33： public RequestWebPage（）

　　34： {

　　35： }

　　36：

　　37： /// <summary>RequestWebPage（string strURL） is the constructor for the class

　　38： /// <see cref="RequestWebPage"/> when called with an URL as parameter.</summary>

　　39： /// <remarks>Stores the URL from the parameter <paramref name="strURL"/> in

　　40： /// the private variable <see cref="m_strURL"/>.</remarks>

　　41： public RequestWebPage（string strURL）

　　42： {

　　43： m_strURL = strURL；

　　44： }

　　45：

　　46： /// <remarks>Sets the value of <see cref="m_strURL"/>.

　　47： /// Returns the value of <see cref="m_strURL"/>.</remarks>

　　48： public string URL

　　49： {

　　50： get { return m_strURL； }

　　51： set { m_strURL = value； }

　　52： }

　　53：

　　54： /// <summary>The GetContent（out string strContent） method：

　　55： /// <para>Included in the <see cref="RequestWebPage"/> class</para>

　　56： /// <para>Uses variable <see cref="m_strURL"/></para>

　　57： /// <para>Used to retrieve the content of a Webpage. The URL

　　58： /// of the Webpage （including http://） must already be

　　59： /// stored in the private variable m_strURL.

　　60： /// To do so， call the constructor of the RequestWebPage

　　61： /// class， or set its property <see cref="URL"/> to the URL string.</para>

　　62： /// </summary>

　　63： /// <remarks>Retrieves the content of the Webpage specified in

　　64： /// the property<see cref="URL"/> and hands it over to the out

　　65： /// parameter <paramref name="strContent"/>.

　　66： /// The method is implemented using：

　　67： /// <list>

　　68： /// <item>The <see cref="System.Net.WebRequestFactory.Create"/>method.</item>

　　69： /// <item>The <see cref="System.Net.WebRequest.GetResponse"/> method.</item>

　　70： /// <item>The <see cref="System.Net.WebResponse.GetResponseStream"/>method</item>

　　71： /// <item>The <see cref="System.IO.Stream.Read"/> method</item>

　　72： /// <item>The <see cref="System.Text.StringBuilder.Append"/> method</item>

　　73： /// <item>The <see cref="System.Text.Encoding.ASCII"/> property together with its

　　74： /// <see cref="System.Text.Encoding.ASCII.GetString"/> method</item>

　　75： /// <item>The <see cref="System.Object.ToString"/> method for the

　　76： /// <see cref="System.IO.Stream"/> object.</item>

　　77： /// </list>

　　78： /// </remarks>

　　79： /// <seealso cref="System.Net"/>

　　80： public bool GetContent（out string strContent）

　　81： {

　　82： strContent = ""；

　　83： // ……

　　84： return true；

　　85： }

　　86： }

　　9.2.3 提供例子

　　要想说明一个对象和方法的用法，最好的办法是提供优秀源代码的例子。因此，不要诧异文档注释也有用于声明例子的标签： <example> and <code>. <example>标签包含了包括描述和代码的整个例子，而 <code> 标签仅包含了例子的代码（令人惊讶）。

　　清单9.7 说明如何实现代码例子。包括的例子用于两个构造函数。你必须给GetContent方法提供例子。

　　清单。7 利用例子解释概念

　　1： using System；

　　2： using System.Net；

　　3： using System.IO；

　　4： using System.Text；

　　5：

　　6： /// <summary>Class to tear a Webpage from a Webserver</summary>

　　7： /// <remarks> …… </remarks>

　　8： public class RequestWebPage

　　9： {

　　10： private const int BUFFER_SIZE = 12

上一页  [1] [2] [3] [4] [5]