Rust: Développer un guide de style doc-commentaire

:+1: pour en avoir discuté. Je veux contribuer aux documents, mais je ne veux pas vous faire plus de travail une fois que c'est fait. ;)

A titre de comparaison, le style Python standard consiste à utiliser l'impératif « Retour le… », qui, je trouve, fonctionne bien :

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

Go a opté pour le style non impératif : http://golang.org/pkg/

Visite pour triage.

Personnellement, je préfère les verbes à l'impératif, et un point à la fin. En ce qui concerne le style de commentaire doc, je ne pense pas que nous devrions imposer une manière particulière à une autre, du moins pas tant que le langage définit plusieurs façons de le faire. Aussi, ma méthode préférée est

/**
 * doc string
 */

Je préfère aussi l'impératif. Le style doit également inclure une syntaxe unifiée pour faire référence aux types et aux arguments, afin que rustdoc puisse correctement les annoter/les hyperlier. C'est sur la route cependant

Visite pour triage. J'ai très peu d'avis à ce sujet.

Style descriptif :

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

Style impératif :

• 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

Je préfère moi-même les versions descriptives car une définition de méthode ne fait rien tant que je ne lui dis pas :

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

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

Je suis sensible à l'argument de kud1ing. De plus, si vous lisez à voix haute une ligne telle qu'elle est présentée dans la doc :

zéro Renvoie l'identité additive, 0.

alors la forme déclarative en fait une vraie phrase "zero" returns the additive identity, 0. .

@Armavica : Qui est en fait une forme courte de The method "zero" returns the additive identity, 0 .

La documentation et l'interface, c'est présenter quelque chose au public. Je pense que la forme impérative a plus de sens, lorsque vous expliquez quoi/comment/pourquoi quelque chose se passe dans la mise en œuvre.

Il y a aussi https://github.com/mozilla/rust/issues/9403 sur le style des exemples dans la documentation.

Charrue.

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

D'après les commentaires ici, le style descriptif (par exemple, "Convertit un octet en chaîne.") semble plus populaire que le style impératif ("Convertir un octet en chaîne."). Je me fiche de la direction que nous prenons, mais ce serait bien d'avoir une décision officielle à ce sujet.

Je pense qu'appeler cela le style impératif est faux. Ce n'est pas impératif, car il ne demande à personne de faire quoi que ce soit. Je pense que c'est l'indicatif présent à la première personne. Je soupçonne que l'envie d'écrire

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

découle de l'état d'esprit « Je suis la fonction. Que dois-je faire ? », c'est donc l'indicatif présent à la première personne.

Cependant, lors de la lecture de la documentation, la plupart des lecteurs traiteront naturellement la fonction comme un sujet à la troisième personne du singulier au lieu d'un sujet à la première personne. À cette fin, la documentation doit être écrite à la troisième personne du singulier au lieu de la première personne.

Le seul argument raisonnable que je puisse voir pour considérer qu'il s'agit de l'impératif plutôt que de l'indicatif présent à la première personne est lorsque la docstring décrit une déclaration de fonction que l'utilisateur est censé implémenter. C'est très courant dans les langages OO, mais dans Rust, cela ne s'applique qu'aux méthodes de trait. Ce cas suggère l'utilisation de l'impératif car il vous indique ce que vous devez faire pour implémenter correctement la méthode.

Mais je ne considère pas cet argument comme convaincant. Le principal cas d'utilisation de la documentation est de dire au lecteur comment _utiliser_ l'API, pas comment l'implémenter. Le nombre d'utilisations d'une API dépasse largement le nombre d'implémentations (dans tous les cas sauf le plus ésotérique). Par conséquent, je pense qu'il est plus logique d'utiliser l'indicatif présent à la troisième personne du singulier que d'utiliser l'impératif, même pour les méthodes de trait.

Autre chose à gérer : les traits d'union ou les tirets :

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

La préférence pour un tiret au lieu d'un trait d'union dans ces types de termes de coordonnées/relation/connexion est une question de préférence de style, et non de « correction » orthographique inhérente ; les deux sont également "corrects", et chacun est le style préféré dans certains guides de style.

J'ai soumis une RFC : https://github.com/rust-lang/rfcs/pull/505