Rust: Entwickeln Sie einen Styleguide für Dokumentkommentare

:+1: für die Diskussion. Ich möchte Dokumente beisteuern, aber ich möchte Ihnen nicht noch mehr Arbeit machen, nachdem es fertig ist. ;)

Zum Vergleich verwendet der Standard-Python-Stil den Imperativ "Return the …", was meiner Meinung nach gut funktioniert:

http://www.python.org/dev/peps/pep-0257/#one -line-docstrings

Go hat sich für den nicht-imperativen Stil entschieden: http://golang.org/pkg/

Besuch zur Triage.

Persönlich bevorzuge ich zwingende Verben und einen Punkt am Ende. Was den Stil von Doc-Kommentaren angeht, denke ich, dass wir keinen bestimmten Weg über einen anderen erzwingen sollten, zumindest nicht, wenn die Sprache mehrere Möglichkeiten definiert, dies zu tun. Außerdem ist mein bevorzugter Weg

/**
 * doc string
 */

Ich bevorzuge auch den Imperativ. Style muss auch eine einheitliche Syntax für den Verweis auf Typen und Argumente enthalten, damit rustdoc sie richtig annotieren/hyperlinken kann. Das ist aber die Straße runter

Besuch zur Triage. Ich habe sehr wenig Meinung dazu.

Beschreibender Stil:

• C# : Sorts the elements ... http://msdn.microsoft.com/en-gb/library/w56d4y5z%28v=vs.85%29.aspx#United %20Kingdom%20%28English%29
• C++ : ... sorts the elements ... http://www.sgi.com/tech/stl/sort.html
• Gehe zu : ... sorts data ... http://golang.org/pkg/sort/#Sort
• Haskel l: ... takes an element and a list and inserts the element into the list ... http://hackage.haskell.org/package/base-4.6.0.1/docs/Data-List.html
• Java : Sorts the specified array ... http://docs.oracle.com/javase/7/docs/api/java/util/Arrays.html
• Ruby : Sorts self in place. http://www.ruby-doc.org/core-2.1.0/Array.html#method -i-sort-21

Imperativer Stil:

• Ocam l: ... sort a list ... http://caml.inria.fr/pub/docs/manual-ocaml/libref/List.html
• Python : Sort the items ... http://docs.python.org/2/tutorial/datastructures.html

Ich selbst bevorzuge die beschreibenden Versionen, weil eine Methodendefinition nichts tut, bis ich sie dazu erteile:

class Machine
{
    // Self-destructs the machine, if necessary.
    void self_destruct();
};

// Self-destruct!
if ( emergency )
  machine.self_destruct();

Ich bin vernünftig für die Argumentation von Kud1ing. Außerdem, wenn Sie eine Zeile so vorlesen, wie sie im Dokument dargestellt wird:

null Gibt die additive Identität 0 zurück.

dann macht die deklarative Form daraus einen echten Satz "zero" returns the additive identity, 0. .

@Armavica : Was eigentlich eine Kurzform von The method "zero" returns the additive identity, 0 .

Dokumentation und Schnittstelle ist, dem Publikum etwas zu präsentieren. Ich finde die Imperativform sinnvoller, wenn man erklärt, was/wie/warum etwas in der Umsetzung passiert.

Es gibt auch https://github.com/mozilla/rust/issues/9403 über den Stil der Beispiele in der Dokumentation.

Pflug.

cc https://github.com/mozilla/rust/issues/12928

Aus den Kommentaren hier scheint der beschreibende Stil (z. B. "Konvertiert ein Byte in eine Zeichenfolge") populärer zu sein als der Imperativstil ("Konvertiert ein Byte in eine Zeichenfolge"). Es ist mir egal, in welche Richtung wir gehen, aber es wäre schön, eine offizielle Entscheidung darüber zu haben.

Ich denke, dass es falsch ist, dies den Imperativ-Stil zu nennen. Es ist nicht zwingend, weil es niemanden anweist, etwas zu tun. Ich denke, es ist das Präsens in der ersten Person. Ich vermute, dass der Drang zu schreiben

/// Frob the twaddle.
fn frob() {}

stammt aus der Denkweise von "Ich bin die Funktion. Was tue ich?", also ist es der Präsens-Indikativ in der ersten Person.

Bei der Lektüre von Dokumentationen behandeln die meisten Leser die Funktion jedoch natürlich als Dritte-Person-Singular-Fach statt als Ich-Fach. Zu diesem Zweck sollte die Dokumentation in der dritten Person Singular statt in der ersten Person verfasst werden.

Das einzige vernünftige Argument, das ich dafür sehen kann, dies als Imperativ und nicht als Indikativ der ersten Person zu betrachten, ist, wenn der Docstring eine Funktionsdeklaration beschreibt, die der Benutzer implementieren soll. Dies ist in OO-Sprachen sehr üblich, aber in Rust gilt dies nur für Trait-Methoden. Dieser Fall empfiehlt die Verwendung des Imperativs, da er Ihnen sagt, was Sie tun müssen, um die Methode korrekt zu implementieren.

Aber ich halte dieses Argument nicht für überzeugend. Der primäre Anwendungsfall für die Dokumentation besteht darin, dem Leser zu sagen, wie er die API _benutzt_, nicht wie er sie implementiert. Die Anzahl der Verwendungen einer API übersteigt bei weitem die Anzahl der Implementierungen (in allen außer den esoterischsten Fällen). Daher glaube ich, dass es sinnvoller ist, den Präsens Indikativ in der dritten Person Singular zu verwenden als den Imperativ, selbst bei Merkmalsmethoden.

Eine andere Sache, mit der man umgehen muss: Bindestriche oder Bindestriche:

https://en.wikipedia.org/wiki/Dash#Relationships_and_connections

Die Bevorzugung eines Gedankenstrichs anstelle eines Bindestrichs in diesen Koordinaten-/Beziehungs-/Verbindungstypen von Begriffen ist eine Frage der Stilpräferenz, nicht der inhärenten orthographischen „Korrektheit“; beide sind gleichermaßen "korrekt", und jeder ist der bevorzugte Stil in einigen Styleguides.

Ich habe einen RFC eingereicht: https://github.com/rust-lang/rfcs/pull/505