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.
