Pre-RFC: documentation comments after code

language design
1

Summary

The documentation comments should be placed after definitions, rather than put before the code.

Motivation

This was inspired by the Cap’n Proto convention. In personal opinion, this should increase code readability especially on small screens. The convention is also used by Python docstrings.

The gotchas with the current convention is described in the first edition of the book.

Actually, this syntax partially (modules doc only) exists in the current convention, although /// is recommended if possible even for such cases.

Detailed Design

To change the syntax while not breaking the world, the module-level syntax for documenting enclosing block (//!) will be allowed (and encouraged) everywhere.

In this syntax, every documentation comment should be put after the declaration. Indents should be made if appropriate (the same rules as if there were actual code).

enum E {
    //! This is an enum
    VarA,
    //! after the line
    VarB, //! inline
}

Documentation should be the first part of function body, as the public documentation doesn’t relate to implementation details, and should follow just after the function signature declaration:

fn f() {
    //! This is a function
    code();
}

In addition, normal comments are encouraged to follow the same rule as well.

Drawbacks

  • Huge effort to migrate.
    • Looks ugly/hard to read to some people?
  • The exclamation mark is harder to type (than just three slashes).

Alternatives

  • Break the world and use /// syntax.
  • Make this just a syntax addition.

Unresolved questions

To be determined.

2

It does work already in functions too!

But the only time I use //! is at the beginning of a file, whether that's a crate or module. For other things written within a file, I don't see an advantage to writing //! inside the item vs. /// just before.

I would find it useful to put doc comments at the end of the line for struct fields and enum variants though.

3

It seems debatable whether this is better (I personally think it’s worse), and even assuming it is, it seems unlikely that the benefits outweigh the drawbacks of changing the current convention and having a different convention than almost all other popular languages.

I think it’s worse because the text between braces should be reserved for the implementation and not for comments about the interface. The alternative of putting the documentation between the declaration and the opening brace can be confusing as it may look like there is no implementation at first glance.

3 Likes
4

See also

which covers just the enum variants (and presumably struct fields) part of this.

4 Likes
5

I do miss the ability to document struct fields and enum variants on the same line.

Aside from that, I like the current conventions the way they are.

2 Likes
6

I would like to mention that Python docstrings use this style.

1 Like
7

My main practical opposition to this, is that it would force an additional level of indentation on the docstrings, making them a bit more constrained. Having the docs live at the same indentation level as the item’s syntax makes them feel somehow more connected.

8

While I miss being able to document enum values inline a la Doxygen, I think there’s a lot of value in having a strict convention and limiting bikeshedding.

I don’t think post-code comments have enough advantages to warrant the additional complexity they’re introduce (technical, and things like having to decide which type of comment to use, when it doesn’t really matter).

9

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