# Doc comment syntax **URL:** \ **Category:** documentation\ **Created:** [December 20, 2020, 4:41pm UTC](https://internals.rust-lang.org/t/doc-comment-syntax/13679 "2020-12-20T16:41:14Z")\ **Posts on this page:** 6\ **Page:** 1
**Author:** ![phlopsi](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/phlopsi/32/7393_2.png) [@phlopsi](https://internals.rust-lang.org/u/phlopsi)\ **Post date:** [December 20, 2020, 4:41pm UTC](https://internals.rust-lang.org/t/doc-comment-syntax/13679/1 "2020-12-20T16:41:14Z")
> [@A Potential Rust Learning Project Group](https://internals.rust-lang.org/t/a-potential-rust-learning-project-group/13620/5): > > Once I learned documenting, I was blown away how easy it was 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: ```rust /// aaaaaaaaaaaaaaaaaa /// bbbbbbbbbbbbbbbbbb /// cccccccccccccccccc ``` is my initial documentation. Now I add another sentence: ```rust /// aaaaaaaaaaaaaaaaaaddddddddd /// bbbbbbbbbbbbbbbbbb /// cccccccccccccccccc ``` and now begins the painful part: ```rust /// aaaaaaaaaaaaaaaaaa ddddddddd /// bbbbbbbbbbbbbbbbbb /// cccccccccccccccccc ``` ```rust /// aaaaaaaaaaaaaaaaaa /// ddddddddd /// bbbbbbbbbbbbbbbbbb /// cccccccccccccccccc ``` ```rust /// aaaaaaaaaaaaaaaaaa /// dddddddddbbbbbbbbbbbbbbbbbb /// cccccccccccccccccc ``` ```rust /// aaaaaaaaaaaaaaaaaa /// dddddddddbbbbbbbbb bbbbbbbbb /// cccccccccccccccccc ``` ```rust /// aaaaaaaaaaaaaaaaaa /// dddddddddbbbbbbbbb /// bbbbbbbbb /// cccccccccccccccccc ``` ```rust /// aaaaaaaaaaaaaaaaaa /// dddddddddbbbbbbbbb /// bbbbbbbbbcccccccccccccccccc ``` ```rust /// aaaaaaaaaaaaaaaaaa /// dddddddddbbbbbbbbb /// bbbbbbbbbccccccccc ccccccccc ``` ```rust /// 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` 👀). 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`. 🤷🏼‍♂️ ---
**Author:** ![vakaras](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/vakaras/32/2156_2.png) [@vakaras](https://internals.rust-lang.org/u/vakaras)\ **Post date:** [December 20, 2020, 10:26pm UTC](https://internals.rust-lang.org/t/doc-comment-syntax/13679/2 "2020-12-20T22:26:38Z")
> 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](https://marketplace.visualstudio.com/items?itemName=stkb.rewrap) plugin for VS Code. ---
**Author:** ![jyn514](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/jyn514/32/13245_2.png) [@jyn514](https://internals.rust-lang.org/u/jyn514)\ **Post date:** [December 21, 2020, 2:20am UTC](https://internals.rust-lang.org/t/doc-comment-syntax/13679/3 "2020-12-21T02:20:35Z")
> 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")]`. ---
**Author:** ![carols10cents](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/carols10cents/32/98_2.png) [@carols10cents](https://internals.rust-lang.org/u/carols10cents)\ **Post date:** [December 25, 2020, 10:12pm UTC](https://internals.rust-lang.org/t/doc-comment-syntax/13679/4 "2020-12-25T22:12:38Z")
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. ---
**Author:** ![phaylon](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/phaylon/32/62_2.png) [@phaylon](https://internals.rust-lang.org/u/phaylon)\ **Post date:** [December 25, 2020, 10:31pm UTC](https://internals.rust-lang.org/t/doc-comment-syntax/13679/5 "2020-12-25T22:31:01Z")
> [@jyn514](#): > > You can do this with `/**` . Probably it should be documented better. These kinds of comments are omitted from the book, but they are [in the reference](https://doc.rust-lang.org/stable/reference/comments.html). Just mentioning it as there's also the `/*! ... */` form to complement `//!`. Addendum: And of course plain `/* ... */` comments which I find indispensable during development. ---
**Author:** ![system](https://sea2.discourse-cdn.com/flex002/user_avatar/internals.rust-lang.org/system/32/14092_2.png) [@system](https://internals.rust-lang.org/u/system)\ **Post date:** [March 25, 2021, 10:31pm UTC](https://internals.rust-lang.org/t/doc-comment-syntax/13679/6 "2021-03-25T22:31:18Z")
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.