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

[bvargin-dev]

Hi,

As suggested in an old and closed but still active discussion, I open another thread because it looks interesting to have the capability to have inline comments. My use case concerns a CLI which should parse the arguments, so in order to not reinvent the wheel I have tried with Clap .

Clap looks to use the rust documentation to display the sub-command comments. Unfortunately, it is not possible today to align the action with the comment. Indeed it becomes more readable when the comment is on the same line (like it is displayed with the sub-command "help").

_// Here an example with sub-commands from GIT_
enum Action {
    Clone,  //< Display file's information rights (size,rights).
    Init,   //< Create an empty Git repository or reinitialize an existing one
    Add     //< Add file contents to the index
}

For this use case, the comment should be "short and pithy" but it does not look to be an anti pattern as discussed in this thread.

Thanks in advance for your feedback and the work you're realizing.

[ThomasMontanoGames]

This would be especially useful for embedded libraries that have a large amount of register definitions. Readability would be significantly improved if the doc comments could be inlined.

[kennytm]

Unfortunately, it is not possible today to align the action with the comment.

Note that Rust Style Guide specifically avoids visual-alignment (rust-lang/style-team#8, rust-lang/rustfmt#4108) because it is not diff-friendly (https://doc.rust-lang.org/stable/style-guide/principles.html). So your example if properly formatted (i.e. after 4108 is fixed) should look like

enum Action {
    Clone, //< Display file's information rights (size,rights).
    Init, //< Create an empty Git repository or reinitialize an existing one
    Add, //< Add file contents to the index
}

//<

Using a new syntax //< is going to break plenty of existing use of the same sequence that are not intended to be a doc-comment (in particular those, for whatever reason, embeds XML into the comment like //<!-- why -->). Sure you could require a new edition, but #2374's //! does not even need to break compatibility.

For this use case,

In practice when you #[derive(clap::*)] you don't just write the doc comment you also bring in other attributes for precise control such as:

#[derive(Subcommand)]
enum Action {
    #[command(arg_required_else_help = true)]
    Clone { //< Clones repos
        remote: String, //< The remote to clone
    },

    #[command(arg_required_else_help = true)]
    Add { //< adds things
        #[arg(required = true)]
        path: Vec<PathBuf>, //< Stuff to add
    },
}

Considering this the clap usage does not look particular easier to read compared with the existing /// style as those #[arg] requires breaking the line anyway.

[SOF3]

@ThomasMontanoGames If it is really so bad for you, you could always do /** Xxx */ Xxx,. Of course rustfmt will still move the attribute to the line above and this is less readable, but this is the current alternative if you insist that it has very significant impact.