Allow docstrings on the right

tools and infrastructure
1

I'm new to Rust and to my surprise rustdoc won't allow me to use docstrings on the right of elements, only on top, if you put anything on right it gives an error.

This won't work:

/// Users.
pub struct User {
    pub name: String  /// User name.
}

You have to do it like this:

/// Users.
pub struct User {
    /// User name.
    pub name: String
}

I think this would be easy to implement using this logic:
If a docstring is not alone in the line, then assign it to the element that's on the left side of it, else assign it to the element bellow it.

Please let me know what you think.
If it's a good idea should a feature request be opened on GitHub?

2

There was a prior RFC on this topic

I think any attempt at opening a new RFC for it would require a very strong consensus from a large group of users that it's an absolutely needed feature (something that I doubt is possible to gather).

3

So, it works like this because /// is actually an attribute, so it works like attributes.

That means that this already compiles:

pub struct Foo {
    x: i32, /// Hi there
    y: i32,
}

But running rustfmt on it will correct it to the more normal

pub struct Foo {
    x: i32,
    /// Hi there
    y: i32,
}

which says to me that this would be a breaking change, and thus would need to be done over an edition, which means it needs even stronger motivation to bother.

What's wrong with just putting the doc comment over the field?

What that would be possible, a rule like that would be unprecedented in Rust -- there's nothing else where parsing depends on formatting like this. I thus suspect it wouldn't happen. (Maybe it could happen with a different syntax.)

11 Likes
4

Good doc strings are hardly going to be as short as "User name" anyway. As soon you put any effort into documenting what your fields actually mean, you'll need to put it in prefix form.

Besides that, non-doc comments already work for this purpose: you can put them wherever you want in the code. (If you were optimizing for reading source-code directly, there'd be no need for doc-comments.) So just get rid of one of those / chars and everything looks peachy.

12 Likes
5

Would it be possible to documented the nested items on the top and have those appear in the generated documentation?

Something like this:

/// Users.
///
/// @name: The user name.
/// @age: The user age.
pub struct User {
    pub name: String,
    pub age: i8
}
6

That seems confusing, since before those docs would show up over the main type. Why would you want that?

7

Also, your idea has the same problem as before that it only works for one-line comments; the comments you've used as an example are basically just the name of the field again, which I wouldn't find helpful at all as a reader of the docs.

8

I know those are basically the name, this is just a simple example to know if something like this would be possible or not. :slightly_smiling_face:

9

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