Rust: Desenvolver guia de estilo de comentário de documento

: +1: para discutir isso. Quero contribuir com documentos, mas não quero fazer mais trabalho para você depois que terminar. ;)

Para efeito de comparação, o estilo Python padrão é usar o imperativo "Devolver o ...", que acho que funciona bem:

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

Go optou pelo estilo não imperativo: http://golang.org/pkg/

Visitando para triagem.

Pessoalmente, prefiro verbos imperativos e um ponto final no final. Quanto ao estilo de comentário de documento, não acho que devemos impor uma maneira particular sobre outra, pelo menos não enquanto a linguagem definir várias maneiras de fazê-lo. Além disso, minha forma preferida é

/**
 * doc string
 */

Eu também prefiro o imperativo. O estilo também precisa incluir uma sintaxe unificada para fazer referência a tipos e argumentos, de forma que rustdoc possa anotá-los / criar um hiperlink adequado. Isso é mais adiante, no entanto

Visitando para triagem. Tenho muito pouca opinião sobre isso.

Estilo descritivo:

• 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
• Vá : ... 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

Eu mesmo prefiro as versões descritivas porque uma definição de método não faz nada até que eu diga para:

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

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

Sou sensível ao argumento de Kud1ing. Além disso, se você ler uma linha em voz alta da forma como é apresentada no documento:

zero Retorna a identidade aditiva, 0.

então a forma declarativa a torna uma sentença real "zero" returns the additive identity, 0. .

@Armavica : Que é na verdade uma forma abreviada de The method "zero" returns the additive identity, 0 .

Documentar e fazer interface é apresentar algo ao público. Acho que a forma imperativa faz mais sentido, quando você explica o que / como / por que algo está acontecendo na implementação.

Também há https://github.com/mozilla/rust/issues/9403 sobre o estilo dos exemplos na documentação.

Arado.

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

A partir dos comentários aqui, o estilo descritivo (por exemplo, "Converte um byte em uma string.") Parece mais popular do que o estilo imperativo ("Converte um byte em uma string."). Não me importo muito para que lado vamos, mas seria bom ter uma decisão oficial sobre isso.

Acho que chamar isso de estilo imperativo é errado. Não é obrigatório, porque não está instruindo ninguém a fazer nada. Acho que é o indicativo presente na primeira pessoa. Eu suspeito que a necessidade de escrever

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

decorre da mentalidade de "Eu sou a função. O que eu faço?", então é o indicativo presente na primeira pessoa.

No entanto, ao ler a documentação, a maioria dos leitores irá naturalmente tratar a função como um assunto de terceira pessoa do singular em vez de um assunto de primeira pessoa. Para tanto, a documentação deve ser redigida na terceira pessoa do singular e não na primeira pessoa.

O único argumento razoável que posso ver para considerar isso como o imperativo, em vez do indicativo presente na primeira pessoa, é quando o docstring descreve uma declaração de função que se espera que o usuário implemente. Isso é muito comum em linguagens OO, mas em Rust isso só se aplica a métodos de característica. Este caso sugere o uso do imperativo porque está dizendo a você o que você deve fazer para implementar o método corretamente.

Mas não considero esse argumento persuasivo. O principal caso de uso para documentação é dizer ao leitor como _usar_ a API, não como implementá-la. O número de usos de uma API supera em muito o número de implementações (em todos os casos, exceto o mais esotérico). Portanto, acredito que faz mais sentido usar o indicativo presente na terceira pessoa do singular do que usar o imperativo, mesmo para métodos de traço.

Outra coisa com que lidar: hypens ou en travessões:

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

A preferência por um travessão em vez de um hífen nesses tipos de termos de coordenada / relação / conexão é uma questão de preferência de estilo, não de "correção" ortográfica inerente; ambos são igualmente "corretos" e cada um é o estilo preferido em alguns guias de estilo.

Enviei um RFC: https://github.com/rust-lang/rfcs/pull/505