demoshop

demo, trying to be the best_

一般在開發共用元件時都會利用 Summary 的標記讓其他共同開發者可以明確的知道這 method 介紹或使用限制,有些專案 Leader 甚至會要求所有的 Public method 都需要標記 Summary (通常是因為要方便產生文件),自己寫的好辦,有些是使用一些 Open source 的 Class 不可能去要求對方作者寫吧,自己補的話可能也只是淪落為使用 Ghost doc 來翻,其實這是可以避開的(當然要專案成員都同意你避開)。

●在預設的情況下並沒有規定 Public method 一定要上 Summary 以下這段 Code 是很ok的

public class Class1
{
    public bool MethodOne()
    {
        return true;
    }

    private bool MethodTwo()
    {
        return false;
    }
}

編譯也不會出任何問題


●但是當專案將匯出 XML 的功能打開後

一樣的 Method 編譯時卻會出現警告

警告 CS1591: 遺漏公用可見型別或成員 'ClassLibrary1.Class1' 的 XML 註解

注意事項如果沒有匯出 XML 那你的 DLL 給他人使用時就不會有相關提示說明(IntellSense)。


●假設要避開這錯誤可以使用以下的指令

#pragma warning disable 1591

    public class Class1
    {
        public bool MethodOne()
        {
            return true;
        }

        private bool MethodTwo()
        {
            return false;
        }
    }

再次編譯,就看不到該項警告了


注意事項雖然可以利用此方式跳開警告,但是如果是專案規定你一定要打 Summary 可不要這樣偷懶跳過,到產文件的時候你就糗了。

回應討論