Wie man richtig eine Erweiterungsmethode dokumentieren

Question

Also, ich habe ein paar Erweiterungsmethoden, für Sachen häufig verwendet, und sie zu dokumentieren, es fiel mir ein, dass ich keine Ahnung , wie man konsequent den summary-Tag in der XML-Kommentare zu schreiben. Zum Beispiel:

    /// <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)

So scheint das Problem zu sein, dass ich weiß nicht, wie konsequent auf diese nervtötenden this Parameter zu beziehen. Außerdem weiß ich nicht, wie man zeigen klar, dass dies eine Erweiterung Methode ist (da ich nicht sicher bin, dass Sandburg und andere Werkzeuge haben noch ihnen gefangen und die Dokumentation automatisch mit Anmerkungen versehen kann es zu zeigen); Ich hasse alle, die manuelle Dokumentation später müssen herausreißen.

Die Frage ist also, was Führung ist es für Methoden Erweiterung zu dokumentieren? Wenn es keine formelle Führung ist, wie alles, was Sie damit umgehen? Wenn wir nicht haben, können wir auf etwas stimmen, damit ich etwas zu gehen? Als obsessive Zwangskontrollfreak, diese Inkonsistenz treibt mich verrückt.

Answer 1

.NET-Sprachen, die Benutzer keine Erweiterungsmethoden unterstützen erfordert die Methode direkt aufrufen und in das Objekt übergeben, die verlängert worden wäre. Deshalb ist es wichtig, diesen Parameter zu dokumentieren und genau beschreiben, warum es notwendig ist, und wie das Verfahren auf sie wirkt.

Dies kann ein wenig schwierig sein, etwa von der Extension-Methode Seite zu denken, aber wenn Sie die Methode von der anderen Seite vorstellen, wo die Menschen eine statische Methode aufrufen, ist es einfacher.

Eine andere Sache ... Manchmal kann man sich finden (wie die Htmlhelper in MVC), wo Sie ein Objekt aus erweitern Konvention anstatt Notwendigkeit. Das bedeutet, es spielt keine Rolle, ob das Objekt, das erweitert wird null ist oder nicht, da das Verfahren auf mich nicht handeln. Während die Konvention (glaube ich) zu werfen, wenn das this Objekt null ist, ziehe ich die Methode vollständig normal und dokumentiert diese Tatsache in der Hilfe (dh lassen „... Das kann null sein“ oder“... null ein gültiger Wert für dieses Argument ist. ")