Rustdoc should support inline or same-line doc comments for enums

[felixc]

Currently if you use the common documentation pattern:

enum Foo {
    Bar,  /// Bar is a value
    Baz,  /// This foo is a baz
    Quux
}

rustdoc will apply the documentation strings to the wrong values (specifically, to the next value after the intended one). Fortunately an error is generated if the last entry in the enum is documented (Quux in this example), but it's also fairly common for the last value to be something like Unknown or Invalid that may not be documented.

It would be nice if this same-line documentation style were supported, as it makes a lot of sense for simple enum values that only have short docs.

[bgamari]

Indeed you are not the only one who has felt the need for this. It would be great if you could write an RFC!

[shepmaster]

Rustdoc supports //! to indicate documenting the thing the comments are "within", and Doxygen has some precedent of forms like ///<, so I'd suggest //< for rustdoc:

enum Foo {
    Bar,  //< Bar is a value
    Baz,  //< This foo is a baz
    Quux
}

[felixc]

I'm not familiar enough with rustdoc to know whether its parser/other implementation detail requires a different comment syntax to support this, but I'd like to note that I don't think that's a key part of this feature. I for one would be happy re-using the existing syntax, and having the interpretation be determined by context (i.e. inline vs. above).

[Centril]

Closing in favor of #2374.

[rzumer]

Why was this issue closed in favor of an open RFC? Now that the pull request is closed, where is it tracked, if at all?

[Centril]

It does not need to be tracked since the RFC was closed.

[rzumer]

That's a shame. I don't think that the fact that particular solution was abandoned means that this is no longer an issue.

Current solutions for enum documentation have to compromise between code readability and access to documentation. For enums with many variants that do not require long comments, doubling the line count is not reasonable, and prefixing variant definitions with block comments or attributes is awkward at best.

Personally, I choose to favor code readability and use regular code comments, which is obviously not ideal, since no documentation will be generated for the variants, but I find it far preferable to adding hundreds of excess lines to get around this issue.

[steveklabnik]

We don’t really use issues in this repo to track anything; they’re just a place for people to discuss ideas. So closing one doesn’t really affect anything other than maybe making older discussion hard to find. Issues can be opened again, or a new one can be made if there’s new stuff to bring to the table, and you want to discuss it before making a new RFC.

…

On Aug 11, 2019, at 11:16 AM, Raphaël Zumer ***@***.***> wrote: That's a shame. I don't think that the fact that particular solution was abandoned means that this is no longer an issue. Current solutions for enum documentation have to compromise between code readability and access to documentation. For enums with many variants that do not require long comments, doubling the line count is not reasonable, and prefixing variant definitions with multi-line comments or attributes is awkward at best. Personally, I choose to favor code readability and use regular code comments, which is obviously not ideal, since no documentation will be generated for the variants, but preferable to adding hundreds of excess lines to get around this issue. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[blueforesticarus]

@rzumer is right, adding (likely 2) extra lines of code harms readability and there shouldn't be a tradeoff between readability and documentation.

[SOF3]

would be great if editors had support to hide (not just collapse) all comments, then there is no tradeoff at all.

[blueforesticarus]

What would actually be good would be a 2 column view.
Code on one side, and the comments on the other.
like 2 column proofs