ameter.</summary>
22: public RequestWebPage(string strURL)
23: {
24:  m_strURL = strURL;
25: }
26:
27: public string URL
28: {
29:  get { return m_strURL; }
30:  set { m_strURL = value; }
31: }
32:
33: /// <summary>The GetContent(out string strContent) method:
34: /// <para>Included in the <see cref="RequestWebPage"/> class</para>
35: /// <para>Uses variable <see cref="m_strURL"/></para>
36: /// <para>Used to retrieve the content of a Webpage. The URL
37: ///  of the Webpage (including http://) must already be
38: ///  stored in the private variable m_strURL.
39: ///  To do so, call the constructor of the RequestWebPage
40: ///  class, or set its property <see cref="URL"/> to the URL string.</para>
41: /// </summary>
42: /// <seealso cref="System.Net"/>
43: /// <seealso cref="System.Net.WebResponse"/>
44: /// <seealso cref="System.Net.WebRequest"/>
45: /// <seealso cref="System.Net.WebRequestFactory"/>
46: /// <seealso cref="System.IO.Stream"/>
47: /// <seealso cref="System.Text.StringBuilder"/>
48: /// <seealso cref="System.ArgumentException"/>
49:
50: public bool GetContent(out string strContent)
51: {
52:  strContent = "";
53:  // ...
54:  return true;
55: }
56: }

9.2.2  添加备注和列表
     <remarks> 标签是规定大量文档的地方。与之相比， <summary>只仅仅规定了成员的简短描述。
     你不限于只提供段落文本（使用<para>标签）。例如，你可以在备注部分包含bulleted（和有限偶数）列表
（list)：

///  <list type="bullet">
///  <item>Constructor
///   <see cref="RequestWebPage()"/> or
///   <see cref="RequestWebPage(string)"/>
///  </item>
///  </list>

    这个list有一项（item），且该item引用了两个不同的构造函数描述。你可以根据需要，任意往list item中添加内
容。
    另一个在备注部分很好用的标签是<paramref>。例如，你可以用<paramref>来引用和描述传递给构造函数的参数：

/// <remarks>Stores the URL from the parameter /// <paramref name="strURL"/> in
/// the private variable <see cref="m_strURL"/>.</remarks>
public RequestWebPage(string strURL)

    在清单9.6中，你可以看到所有的这些以及前面的标签正在起作用。

    清单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]