Pre-RFC: Documentation conventions

[steveklabnik]

Yeah, I’m not sure what the line is either, @brson.

I will say the reason I went with inline over end is because markdown doesn’t have footnote syntax. if it did, I would prefer it as well. Though maybe markdown’s [][] link style would work as psuedo-footnotes?

[nikomatsakis]

I found the comments about which sort of block comment to use and so on a little confusing. For example, the block example is not a doc comment, so it seems out of scope for this RFC. In general, formatting issues seem less important than guidelines that affect the structure of documentation or what it will look like after rustdoc (in other words, iiuc, the aim of this RFC is to ensure that rustdoc output across projects follows consistent conventions, not the source itself).

I may be alone in this, but I strongly prefer inner comments for documentation, and I strongly strongly prefer /*! */ to //!. Hence I would write something like:

fn foo() {
    /*!
     * Comment
     */
}

My reasoning is that, when reading the raw code, I want to see the fn name and signature first, and read the detailed comments later. Therefore, I prefer an inner comment. It also means the comment is indented inside of the thing it applies to. You could argue for using //! except that it provokes a “OH MY EYES MY EYES” reaction for me, particularly when repeating across multiple lines. Unfortunately, there are various cases where inner comments can’t be used (commenting fields in a struct, for example), so I could imagine preferring to always use /// for consistency.

Like brson, I prefer non-inline links because they are easier to read in the raw format. I don’t quite understand your comment re: footnotes – are you just saying that the raw notation doesn’t resemble the HTML output?

[Gankro]

Some misc inconsistent style things I’ve pondered while prodding at API docs:

Tenses: “gets a reference to the map’s key” vs “get a reference to the map’s key”

Genericity/Specificity: “get a reference to this map’s key” vs “get a reference to a map’s key” vs “get a reference to the map’s key” vs “get a reference to the HashMap’s key” etc

Seemingly trivial/redundant things that need to be doc’d. e.g. if I have:

pub enum Entry {
    Vacant(VacantEntry),
    Occupied(OccupiedEntry),
}

pub struct VacantEntry { ... }
pub struct OccupiedEntry { ... }

I need to document all the types, and the individual variants. Should I duplicate descriptions of the variants on the structs, or should different concerns be addressed at different locations, or should one simply “redirect” the user to the other?

[seanmonstar]

I strongly strongly prefer /*! */ to //!

A reason to use // instead of /* */ is that the latter can interfere with commenting out large blocks of code (such as testing an idea without deleting everything).

/*
struct Foo;

// more stuff ...

fn foo() {
    /*! comment */ // <- BOOM
}

*/

[nathantypanski]

Tenses:“gets a reference to the map’s key” vs “get a reference to the map’s key”

The standard for that in the guidelines is

The summary line should be written in third person singular present indicative form. Basically, this means write “Returns” instead of “Return”.

I need to document all the types, and the individual variants. Should I duplicate descriptions of the variants on the structs, or should different concerns be addressed at different locations, or should one simply “redirect” the user to the other?

The behavior of the struct VacantEntry should (presumably) be documented under VacantEntry, and a reference to this as it pertains to the Entry struct should be documented under Entry. This is the only sane way to recommend documenting Enums in general - imagine an Enum with 50 variants; documenting the types contained in their variants as part of the Enum makes absolutely no sense.

[mrec]

Could you provide some concrete examples of the sort of thing that make a good “cross-cutting” guide? That section is a bit minimalist at the moment.

[Gankro]

The standard for that in the guidelines is

Ah, good catch! Missed that.

The behavior of the struct VacantEntry should (presumably) be documented under VacantEntry, and a reference to this as it pertains to the Entry struct should be documented under Entry. This is the only sane way to recommend documenting Enums in general - imagine an Enum with 50 variants; documenting the types contained in their variants as part of the Enum makes absolutely no sense.

Rust still requires that the variants be documented individually (at least, I recall running into that at one point, maybe that’s changed?), so what does one say about trivial wrapper variants? “See <WrappedType> for details”?

[nikomatsakis]

On Wed, Sep 17, 2014 at 07:09:38PM +0000, seanmonstar wrote:

[P1start]

A reason to use // instead of /* */ is that the latter can interfere with commenting out large blocks of code (such as testing an idea without deleting everything).

/* ... */ comments can be nested, so I don’t think that’s a problem.

[treeman]

Good! Some thoughts:

If we want to only use //! why should we keep /!* */ at all? And what use does #[doc=""] and #[doc="";] have? See #6782.

Do we want to mention runnable examples through playground? See #9403.

Also we might want to standardize whether detailed descriptions and examples go on the type or on the module. See #14967.

Is it # Examples or # Example even if there is only a single example?

As a slight aside: what are the different rustdoc modifiers and where can I find them? should_fail for example.

I personally prefer

[some paper][]

[some paper]: http://www.foo.edu/something.pdf

over

[some paper](http://www.foo.edu/something.pdf)

They render the same but I find it a lot easier to read the source, especially if there are many long links.

You mention that the summary line should be written in third person form. Why not the rest as well?

[steveklabnik]

I found the comments about which sort of block comment to use and so on a little confusing. For example, the block example is not a doc comment, so it seems out of scope for this RFC. In general, formatting issues seem less important than guidelines that affect the structure of documentation or what it will look like after rustdoc (in other words, iiuc, the aim of this RFC is to ensure that rustdoc output across projects follows consistent conventions, not the source itself).

As @brson said, I see this as a conventions RFC, which means it’s more of a “This is how good Rust docs look like” than a specific kind of change to software.

[quote=“nikomatsakis, post:5, topic:521, full:true”]I may be alone in this, but I strongly prefer inner comments for documentation, and I strongly strongly prefer /*! */ to //!. [/quote]

I’m just repeating our current guidelines here. I actually feel very much the opposite of you, but that doesn’t matter unless we’re looking to change the current convention.

[quote=“nikomatsakis, post:5, topic:521, full:true”]Like brson, I prefer non-inline links because they are easier to read in the raw format. I don’t quite understand your comment re: footnotes – are you just saying that the raw notation doesn’t resemble the HTML output? [/quote]

I’m saying that Markdown does not have a way to express footnotes, and so we would have to develop some sort of custom extension to enable them, if we wanted that as a guideline.

[steveklabnik]

[quote=“treeman, post:13, topic:521, full:true”] Good! Some thoughts:

If we want to only use //! why should we keep /!* */ at all?[/quote]

If I were Rust BDFL, I would remove them, personally.

[quote] And what use does #[doc=""] and #[doc="";] have? See #6782. [/QUOTE]

It’s an implementation detail, the comments de-sugar to the attributes.

Do we want to mention runnable examples through playground? See #9403.

Rustdoc already inserts these links where appropriate.

Also we might want to standardize whether detailed descriptions and examples go on the type or on the module. See #14967.

Yes, this is a big thing I left out. Good call.

Is it # Examples or # Example even if there is only a single example?

Probably should always be examples for tooling purposes, I’d guess.

[dradtke]

I just want to say that the rust.vim scripts help a lot with the usability of line comments over block comments. @seanmonstar makes a good argument for line comments instead of block, but having to repeatedly adjust your text to be properly formatted and include /// or //! at the start of every line can make writing documentation a pain in the ass, and rust.vim’s automatic formatting for new and joined lines is the only reason I’ve favored it over block comments.

Also, for what it’s worth, I’m for third-person form (“sorts a list”) over first-person (“sort a list”). It’s much more readable IMO.

[pczarn]

Doc-only modules, e.g. trans/doc.rs and borrowck/doc.rs legitimately use /*! ... */ comments. By the way, I prefer /// or //! for documenting other items.

[nikomatsakis]

As @brson said, I see this as a conventions RFC, which means it’s more of a “This is how good Rust docs look like” than a specific kind of change to software.

I wasn’t advocating any change to software, I was just saying that your interpretation of “look like”, I suppose, includes how the docs look in the original source, whereas my interpretation includes only the formatted output.

I’m saying that Markdown does not have a way to express footnotes, and so we would have to develop some sort of custom extension to enable them, if we wanted that as a guideline.

I agree that footnote support in Markdown would be nice, but I don’t really see how it’s relevant to the question of how best to format a link in the raw source.

[nikomatsakis]

As @brson said, I see this as a conventions RFC, which means it’s more of a “This is how good Rust docs look like” than a specific kind of change to software.

To clarify what I meant in my reply, let me try again. All I was saying is that suggestions like “use third-person form”, making it clear what sorts of items require documentation and which do not, or specifying sections like # Parameters or what have you affect the final rendered output and can be helpful for ensuring a consistent “look and feel” to Rust documentation. On the other hand, the details of how someone wrote their markdown links or which kind of comment they chose do not affect the final output. I am not saying they are necessarily out of scope, but they may be more appropriate for a general coding conventions document, versus something specific to writing docs (or one could imagine the general coding conventions document forwarding to this one).

[nikomatsakis]

A reason to use // instead of /* */ is that the latter can interfere with commenting out large blocks of code (such as testing an idea without deleting everything).

Since my by e-mail reply failed, I just wanted to point out that this is generally not an issue for documentation comments specifically. That is, if I want to comment out a large block of code, I always use // for many reasons (it’s very obvious that things are commented out, for one thing!). (Also, /* and */ can be nested, but I still think // is better for commenting out a big block of code temporarily.)

[benh]

If we’re specifying sections like parameters and examples and whatnot to ensure consistency, maybe we really want to switch to something more structured than markdown to get that sort of consistency out of the box.

[dhardy]

Personally I think using comments to disable blocks of code is wrong. In C/C++ I always use #if 0 ... #endif which (a) is nesting (though that isn’t a problem in Rust), (b) the editor usually highlights appropriately and © is obviously not a form of documentation. Shouldn’t there be an equivalent in Rust?

Otherwise, no comment, except that specifying American English seems a bit much.

[steveklabnik]

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.