1: using System; 2: using System.Net; 3: using System.IO; 4: using System.Text; 5: 6: /// Class to tear a Webpage from a Webserver 7: public class RequestWebPage 8: { 9: private const int BUFFER_SIZE = 128; 10: 11: /// m_strURL stores the URL of the Webpage 12: private string m_strURL; 13: 14: /// RequestWebPage() is the constructor for the class 15: /// when called without arguments. 16: public RequestWebPage() 17: { 18: } 19: 20: /// RequestWebPage(string strURL) is the constructor for the class 21: /// when called with an URL as parameter. 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: /// The GetContent(out string strContent) method: 34: /// Included in the class 35: /// Uses variable 36: /// Used to retrIEve the content of a Webpage. The URL 37: /// of the Webpage (includinghttp://) 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 to the URL string. 41: /// 42: /// 43: /// 44: /// 45: /// 46: /// 47: /// 48: /// 49: 50: public bool GetContent(out string strContent) 51: { 52: strContent = ""; 53: // ... 54: return true; 55: } 56: }
/// Stores the URL from the parameter /// in /// the private variable . 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: /// Class to tear a Webpage from a Webserver 7: /// The class RequestWebPage provides: 8: /// Methods: 9: /// 10: /// Constructor 11: /// or 12: /// 13: /// 14: /// 15: /// 16: /// PropertIEs: 17: /// 18: /// 19: /// 20: /// 21: /// 22: /// 23: /// 24: public class RequestWebPage 25: { 26: private const int BUFFER_SIZE = 128; 27: 28: /// m_strURL stores the URL of the Webpage 29: private string m_strURL; 30: 31: /// RequestWebPage() is the constructor for the class 32: /// when called without arguments. 33: public RequestWebPage() 34: { 35: } 36: 37: /// RequestWebPage(string strURL) is the constructor for the class 38: /// when called with an URL as parameter. 39: /// Stores the URL from the parameter in 40: /// the private variable . 41: public RequestWebPage(string strURL) 42: { 43: m_strURL = strURL; 44: } 45: 46: /// Sets the value of . 47: /// Returns the value of . 48: public string URL 49: { 50: get { return m_strURL; } 51: set { m_strURL = value; } 52: } 53: 54: /// The GetContent(out string strContent) method: 55: /// Included in the class 56: /// Uses variable 57: /// Used to retrIEve the content of a Webpage. The URL 58: /// of the Webpage (includinghttp://) 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 to the URL string. 62: /// 63: /// Retrieves the content of the Webpage specifIEd in 64: /// the property and hands it over to the out 65: /// parameter . 66: /// The method is implemented using: 67: /// 68: /// The method. 69: /// The method. 70: /// The method 71: /// The method 72: /// The method 73: /// The property together with its 74: /// method 75: /// The method for the 76: /// object. 77: /// 78: /// 79: /// 80: public bool GetContent(out string strContent) 81: { 82: strContent = ""; 83: // ... 84: return true; 85: } 86: }
9.2.3 提供例子 要想說明一個對象和方法的用法,最好的辦法是提供優秀源代碼的例子。因此,不要詫異文檔注釋也有用於聲明例子的標簽: and 。 標簽包含了包括描述和代碼的整個例子,而 標簽僅包含了例子的代碼(令人驚訝)。 清單9.7 說明如何實現代碼例子。包括的例子用於兩個構造函數。你必須給GetContent方法提供例子。
清單.7 利用例子解釋概念
1: using System; 2: using System.Net; 3: using System.IO; 4: using System.Text; 5: 6: /// Class to tear a Webpage from a Webserver 7: /// ... 8: public class RequestWebPage 9: { 10: private const int BUFFER_SIZE = 12