-
Notifications
You must be signed in to change notification settings - Fork 12.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Develop doc-comment style guide #4361
Comments
👍 for discussing this. I want to contribute docs, but I don't want to make more work for you after it's done. ;) |
For comparison, standard Python style is to use the imperative "Return the …", which I find works well: http://www.python.org/dev/peps/pep-0257/#one-line-docstrings |
Go has settled on the non-imperative style: http://golang.org/pkg/ |
Visiting for triage. Personally, I prefer imperative verbs, and a period at the end. As for doc comment style, I don't think we should enforce any particular way over another, at least not while the language defines multiple ways to do it. Also, my preferred way is
|
I also prefer the imperative. Style also needs to include a unified syntax for refering to types and arguments, so |
Visiting for triage. I have very little opinion about this. |
Descriptive style:
Imperative style:
|
I prefer the descriptive versions myself because a method definition does not do anything until i tell it to:
|
I am sensible to kud1ing's argument. Furthermore, if you read aloud a line the way it is presented in the doc:
then the declarative form makes it a real sentence |
@Armavica: Which is actually a short form of Documentating and interface is presenting something to the audience. I think the imperative form makes more sense, when you explain what/how/why something is happening in the implementation. |
There's also #9403 about the style of the examples in documentation. |
P-low. |
cc #12928 |
From the comments here, descriptive style (e.g., "Converts a byte to a string.") seems more popular than imperative style ("Convert a byte to a string."). I don't much care which way we go, but it would be nice to have an official decision on this. |
I think that calling this the imperative style is wrong. It's not imperative, because it's not instructing anyone to do anything. I think it's the first-person present indicative. I suspect that the urge to write /// Frob the twaddle.
fn frob() {} stems from the mindset of "I am the function. What do I do?", so it's the first-person present indicative. However, when reading documentation, most readers will naturally treat the function as a third-person singular subject instead of a first-person subject. To that end, the documentation should be written in the third-person singular instead of the first-person. The only reasonable argument I can see for considering this to be the imperative rather than the first-person present indicative is when the docstring describes a function declaration that the user is expected to implement. This is very common in OO languages, but in Rust that only applies to trait methods. This case suggests the use of the imperative because it's telling you what you must do in order to implement the method correctly. But I don't consider this argument to be persuasive. The primary use-case for documentation is telling the reader how to use the API, not how to implement it. The number of uses of an API vastly outstrips the number of implementations (in all but the most esoteric of cases). Therefore, I believe that it makes more sense to use the present indicative in the third-person singular than it does to use the imperative, even for trait methods. |
Another thing to deal with: hypens or en dashes: https://en.wikipedia.org/wiki/Dash#Relationships_and_connections
|
For crates `alloc`–`collections`. This is mostly just updating a few function/method descriptions to use the indicative style. cc #4361; I’ve sort of assumed that the third-person indicative style has been decided on, but I could update this to use the imperative style if that’s preferred, or even update this to remove all function-style-related changes. (I think that standardising on one thing, even if it’s not the ‘best’ option, is still better than having no standard at all.) The indicative style seems to be more common in the Rust standard library at the moment, especially in the newer modules (e.g. `collections::vec`), more popular in the discussion about it, and also more popular amongst other languages (see #4361 (comment)).
I have submitted an RFC: rust-lang/rfcs#505 |
This chapter covers writing documentation in depth. Fixes rust-lang#4361 Fixes rust-lang#12862 Fixes rust-lang#14070 Fixes rust-lang#14967
With a lot of library code expected to change before the 1.0 release, it doesn't make much sense to do this now, but the core and std libraries should use a consistent style for API documentation. The wiki makes some attempt at specifying conventions, but these need to be fleshed out and actually applied to the codebase.
Right now, some doc-comments are written in the third-person indicative:
and some are written in the imperative:
These two examples illustrate another inconsistency: Some summaries (the first line of the comment) have no terminal punctuation, while others end with a period.
One more thing that varies is the comment style itself. Some doc-comments look like
while others look like
Once these rules (and others) are codified, I'd be happy to start going through the doc-comments and updating them.
The text was updated successfully, but these errors were encountered: