Hi, I often find myself browsing through a library and not paying attention to the (unrendered) doc comments. I usually only read them when I am browsing the rendered documentation on docs.rs. However when browsing the code they often clutter a lot of screen space.
So I thought, what if we allowed to separate code and documentation altogether? There could be separate files which reference items in the source code and document them.
(Commenting about the motivation) rust-analyzer implements LSP folding-range request for the multi-line comments https://github.com/rust-analyzer/rust-analyzer/blob/018a6cac072767dfd630c22e6d9ce134b7bb09af/crates/ide/src/folding_ranges.rs#L155. For VSCode, "Fold All Block Comments" command can be used.
Thanks for the hint, this doesn't work on Github however.
There is an accepted RFC of including external file as a doc comment https://github.com/rust-lang/rust/issues/44732 (external_doc feature, currently unstable).
Perfect! Thanks 
It's worth noting that separating documentation and code does also have a significant negative effect. Comments/documentation are already at high risk of getting out of date even when right next to the code they describe; putting more distance increases the risk dramatically.
There's certainly a balance to strike. Putting examples in a separate but included file for example seems to combine the two approaches: It removes a potentially large amount of documentation from the source, that is incidentally likely least relevant to the implementation internals, and is also compile checked so that it's less likely to silently become stale.
It's less likely to silently become stale compared to non-example docs, but not compared to examples next to the code.
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.