Doc comment syntax

documentation
1

My experience with documentation is a world of pain. Having to deal with manually formatting your documentation with careful placement of /// is driving me crazy. Whenever I want to improve documentation, I have the following problem:

/// aaaaaaaaaaaaaaaaaa
/// bbbbbbbbbbbbbbbbbb
/// cccccccccccccccccc

is my initial documentation. Now I add another sentence:

/// aaaaaaaaaaaaaaaaaaddddddddd
/// bbbbbbbbbbbbbbbbbb
/// cccccccccccccccccc

and now begins the painful part:

/// aaaaaaaaaaaaaaaaaa
ddddddddd
/// bbbbbbbbbbbbbbbbbb
/// cccccccccccccccccc

/// aaaaaaaaaaaaaaaaaa
/// ddddddddd
/// bbbbbbbbbbbbbbbbbb
/// cccccccccccccccccc

/// aaaaaaaaaaaaaaaaaa
/// dddddddddbbbbbbbbbbbbbbbbbb
/// cccccccccccccccccc

/// aaaaaaaaaaaaaaaaaa
/// dddddddddbbbbbbbbb
bbbbbbbbb
/// cccccccccccccccccc

/// aaaaaaaaaaaaaaaaaa
/// dddddddddbbbbbbbbb
/// bbbbbbbbb
/// cccccccccccccccccc

/// aaaaaaaaaaaaaaaaaa
/// dddddddddbbbbbbbbb
/// bbbbbbbbbcccccccccccccccccc

/// aaaaaaaaaaaaaaaaaa
/// dddddddddbbbbbbbbb
/// bbbbbbbbbccccccccc
ccccccccc

/// aaaaaaaaaaaaaaaaaa
/// dddddddddbbbbbbbbb
/// bbbbbbbbbccccccccc
/// ccccccccc

I wish I could do //* … *// (multi-line doc comment) and have cargo-fmt take care of the line length for me, so I only have to worry about the documentation part, not the formatting.

IMO, stuffing the complete documentation into the source code files is terrible. Documentation is important, but when I'm looking through some code, I don't want to be bothered by ⅔ of an *.rs file bloated with doc comments (looking at you, std :eyes:). I'd much rather put only summary (one sentence to describe the module/struct/function), error/panic and safety doc comments in the source code directly and everything else in a *.rsdoc file or similar, which would not have to be plastered with //! and /// everywhere.

If I want to read the complete documentation nicely formatted, I use cargo-doc. :man_shrugging:t3:

2

My experience with documentation is a world of pain. Having to deal with manually formatting your documentation with careful placement of /// is driving me crazy.

All code editors I know can do that for you. For example, there is Rewrap plugin for VS Code.

1 Like
3

wish I could do //* … *// (multi-line doc comment) and have cargo-fmt take care of the line length for me, so I only have to worry about the documentation part, not the formatting.

You can do this with /**. Probably it should be documented better.

I'd much rather put only summary (one sentence to describe the module/struct/function), error/panic and safety doc comments in the source code directly and everything else in a *.rsdoc file or similar

On nightly you can use #[doc = include_str!("my_docs.md")].

7 Likes
4

I extracted this thread because it probably wouldn't be a part of the Rust Learning Project Group, and didn't want it to get lost in that post's comments.

3 Likes
5

These kinds of comments are omitted from the book, but they are in the reference. Just mentioning it as there's also the /*! ... */ form to complement //!.

Addendum: And of course plain /* ... */ comments which I find indispensable during development.

2 Likes
6

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