Rust: Desarrollar una guía de estilo de comentarios de documentos

: +1: por discutir esto. Quiero contribuir con documentos, pero no quiero hacer más trabajo para ti una vez hecho. ;)

A modo de comparación, el estilo estándar de Python es usar el imperativo "Devolver el ...", que encuentro que funciona bien:

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

Go se ha decidido por el estilo no imperativo: http://golang.org/pkg/

Visitando para triaje.

Personalmente, prefiero los verbos imperativos y un punto al final. En cuanto al estilo de los comentarios de documentos, no creo que debamos imponer ninguna forma en particular sobre otra, al menos no mientras el lenguaje define múltiples formas de hacerlo. Además, mi forma preferida es

/**
 * doc string
 */

Yo también prefiero el imperativo. El estilo también debe incluir una sintaxis unificada para hacer referencia a tipos y argumentos, por lo que rustdoc puede anotarlos / hipervincularlos correctamente. Eso es en el camino aunque

Visitando para triaje. Tengo muy poca opinión sobre esto.

Estilo descriptivo:

• 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
• Ir : ... 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

Estilo imperativo:

• 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

Yo mismo prefiero las versiones descriptivas porque la definición de un método no hace nada hasta que le digo que:

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

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

Soy sensible al argumento de Kud1ing. Además, si lee en voz alta una línea de la forma en que se presenta en el documento:

cero Devuelve la identidad aditiva, 0.

entonces la forma declarativa la convierte en una oración real "zero" returns the additive identity, 0. .

@Armavica : que en realidad es una forma corta de The method "zero" returns the additive identity, 0 .

La documentación y la interfaz es presentar algo a la audiencia. Creo que la forma imperativa tiene más sentido cuando explica qué / cómo / por qué está sucediendo algo en la implementación.

También hay https://github.com/mozilla/rust/issues/9403 sobre el estilo de los ejemplos en la documentación.

Arado.

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

De los comentarios aquí, el estilo descriptivo (por ejemplo, "Convierte un byte en una cadena") parece más popular que el estilo imperativo ("Convierte un byte en una cadena"). No me importa mucho el camino que tomemos, pero sería bueno tener una decisión oficial al respecto.

Creo que llamar a esto el estilo imperativo está mal. No es imperativo, porque no está instruyendo a nadie para que haga nada. Creo que es el presente de indicativo en primera persona. Sospecho que las ganas de escribir

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

proviene de la mentalidad de "Yo soy la función. ¿Qué hago?", por lo que es el presente de indicativo en primera persona.

Sin embargo, al leer la documentación, la mayoría de los lectores tratarán naturalmente la función como un sujeto en tercera persona del singular en lugar de como un sujeto en primera persona. Para ello, la documentación debe estar escrita en tercera persona del singular en lugar de en primera persona.

El único argumento razonable que puedo ver para considerar que este es el imperativo en lugar del presente de indicativo en primera persona es cuando la cadena de documentos describe una declaración de función que se espera que el usuario implemente. Esto es muy común en los lenguajes OO, pero en Rust solo se aplica a los métodos de rasgos. Este caso sugiere el uso del imperativo porque le dice lo que debe hacer para implementar el método correctamente.

Pero no considero que este argumento sea convincente. El caso de uso principal de la documentación es decirle al lector cómo _usar_ la API, no cómo implementarla. La cantidad de usos de una API supera ampliamente la cantidad de implementaciones (en todos los casos, excepto en los más esotéricos). Por lo tanto, creo que tiene más sentido usar el presente de indicativo en tercera persona del singular que usar el imperativo, incluso para los métodos de rasgo.

Otra cosa con la que lidiar: guiones o guiones cortos:

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

La preferencia por un guión corto en lugar de un guión en estos tipos de términos de coordenadas / relación / conexión es una cuestión de preferencia de estilo, no de "corrección" ortográfica inherente; ambos son igualmente "correctos", y cada uno es el estilo preferido en algunas guías de estilo.

Envié un RFC: https://github.com/rust-lang/rfcs/pull/505