확장 방법을 올바르게 문서화하는 방법

Question

그래서, 나는 일반적으로 사용되는 물건에 대한 몇 가지 확장 방법이 있으며, 문서화 할 때는 내가 가지고있는 것이 나에게 일어났다. 몰라요 일관되게 쓰는 방법 summary XML 댓글에 태그. 예를 들어:

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

vs.

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

그래서 문제는 그 성가신 this 매개 변수. 또한, 나는 이것이 확장 방법임을 명확하게 나타내는 방법을 모른다 (Sandcastle과 다른 도구가 아직 그들을 따라 잡았으며 설명서에 자동으로 주석을 달 수 있다고 확신하지 못하기 때문에); 나중에 모든 수동 문서를 찢어내는 것을 싫어합니다.

문제는 확장 방법을 문서화하기위한 지침이 무엇입니까? 공식적인 지침이 없다면 어떻게 처리합니까? 우리가하지 않았다면, 우리는 무언가에 투표 할 수 있도록 할 수 있습니까? 강박적인 강박 제어 괴물로서,이 불일치로 인해 나를 화나게합니다.

Answer 1

확장 방법을 지원하지 않는 .NET 언어는 사용자가 메소드를 직접 호출하고 확장 된 객체를 전달해야합니다. 따라서이 매개 변수를 문서화하고 필요한 이유와 방법이 어떻게 작용하는지 정확하게 설명하는 것이 중요합니다.

이것은 확장 방법 측면에서 생각하기가 조금 어려울 수 있지만, 사람들이 정적 방법을 부르는 다른 쪽에서 방법을 구상하면 더 쉽습니다.

다른 하나 ... 때로는 자신을 찾을 수 있습니다 (MVC의 HtmlHelper와 같이). 협약 필요보다는. 이것은 확장되는 객체가 메소드에 작용하지 않기 때문에 객체가 null인지 아닌지는 중요하지 않다는 것을 의미합니다. 컨벤션이 (내가 믿는다)는 this 객체는 null입니다. 나는 방법을 정상적으로 완성하고 도움 으로이 사실을 문서화하는 것을 선호합니다 (즉, "... 이것은 null이 될 수 있습니다"또는 "... NULL은이 인수의 유효한 값입니다.").