如何正確記錄擴展方法

因此，我有一些擴展方法，對於常用的東西，並在記錄它們時，我想到我有不知道如何一致地在XML中編寫summary標記註釋。例如：如何正確記錄擴展方法

/// <summary> 
    ///  Gets a subset of characters from the left-hand side of a string. 
    /// </summary> 
    public static string Left(this string value, int length)

與

/// <summary> 
    ///  Gets the name of the month for this date. 
    /// </summary> 
    public static string MonthName(this DateTime value)

所以，這個問題似乎是，我不知道如何一致指的是討厭的this參數。此外，我不知道如何清楚地表明這是一種擴展方法（因爲我不確定Sandcastle和其他工具是否已經趕上了它們，並且可以自動註釋文檔以顯示它）。我不希望以後要把所有的手動文檔都撕掉。

所以問題是，有什麼指導文件的擴展方法？如果沒有正式的指導，你們如何處理？如果我們沒有，我們是否可以對某件事進行投票，這樣我就可以繼續下去了？作爲一個強迫性的控制狂，這種不一致使我發瘋。

來源

2008-12-31 Mike Hofer

我一直在爲自己爭取這個問題，我還沒有得出結論。我花了一段時間來命名這個對象「this」。在VB中這似乎是一件很自然的事情，但是我並沒有把它當作一個正常的函數來處理，它也是如此。 – 2009-01-01 02:52:08

不支持擴展方法的.NET語言將要求用戶直接調用該方法並傳入將要擴展的對象。因此，記錄此參數並準確描述爲什麼需要以及該方法如何處理它非常重要。

從擴展方法的角度來看，這可能有點難以想象，但是如果你從另一方面設想方法，人們在調用靜態方法的時候，它更容易。

還有一件事......有時你可能會發現自己（例如MVC中的HtmlHelper），在這裏你將對象擴展出約定而不是必需的。這意味着擴展的對象是否爲null並不重要，因爲該方法不會對其執行操作。雖然約定（我相信）是在this對象爲空時拋出，但我更願意讓方法正常完成並在幫助中記錄這個事實（即「...可以爲null」或「... null是這個論點的有效值。「）

來源

2008-12-31 19:51:09 Will

只是一個說明......儘管我希望儘可能讓null這個值滑動，但我相信框架中的標準是無論如何拋出。 – Will 2009-10-02 13:50:49

如何正確記錄擴展方法

回答

相關問題