Is there a way to "include" markdown into module documentation?


#1

Very often, one wants to place a deluge of documentation into a particular module. I’m pretty sure that as it stands, all of this documentation needs to live in //! comments inside of the source code. From a programming perspective, however, I have very often had to scroll past hundreds of lines of documentation that was mostly irrelevant to the source code itself but was collocated with the source code because it was paramount for it to appear in the module. This is also bad for source code changes; whenever I make a lot of changes to a particular file’s documentation, it might look like I have made a lot of changes to the actual functionality of the module… until I read the commit message and see something like “added a tutorial and three examples”.

Because of this I’ve very often gotten into the habit of writing a lot of documentation in exterior markdown files and then linking to these files in the module’s documentation but usually it saddens me that the documentation is one more step removed from the module it is related to.

Further: even the lengthy introductions of modules that will usually find themselves in doc comments inside of the source files is a bit of a drag to scroll through. So, in accordance to the title: is there a way to “include” arbitrary markdown into documentation via rust-doc? And if not, is this considered useful enough that it should be included in the rust-doc utility? Because it is possible that the way things are right now encourages a lot more discipline and structure: keep module documentation to a minimum and lengthy excursions into tutorials or philosophy should be relegated to external markdown files. And normally I follow this, but there is an interesting middle ground that I think gets neglected: documentation that should necessarily appear inside of the module, but is long enough to distract from the code and also cause “noise” in commit chains.


#2

There isn’t currently, there’s an open Rustdoc bug for such a thing though.


#3

Yes, this would be a very nice feature.

Current workaround: Write a build.rs script that takes your .md file (or, each of them), prepends //! to every line and saves it somewhere else. Then, use include!.


#4

My question would be if your editor should be able to collapse the comments. I know with Java and Eclipse I was able to collapse comments if they started filling up the file too much. This doesn’t help the “large” change in the comments issue. Maybe the module documentation should be in it’s own file but leave the function comments with the code.

I kind of feel like the editor should be helping make the source more readable. That’s what it’s doing with the basic syntax highlighting, and with the more advanced editors collapsing comments and functions and allow you to click on a method call and jump to the implementation of that call.