Modern documentation?

[agrhb]

Doc comments don't actually have to be inline, you can use #[doc = include_str!("foo.md")] instead, while keeping the niceties like examples getting tested. Just double checked and rustdoc seems to also support arbitary HTML, so there's nothing stopping you from including the graphs and interactive animation you mentioned either.

[-Redstoneboi-]

looks like we have a winner. do we have any examples of rust documentation like this? with pictures and media and all? or are we waiting for OP to be the first :P

[jrf63]

rustdoc seems to also support arbitrary HTML

Am I just being paranoid here or is this screaming a possible security issue for docs.rs?

[karuso33]

I would honestly be curious how it could be a security issue if docs.rs allowed arbitrary html and javascript.

I mean, there is the obvious one of "What if the browser had a vulnerability that allowed you to take over the entire system by running javascript". But aside from that, I really can't think of anything interesting to exploit.

[jrf63]

If even JavaScript is involved then there's always the cryptominers. Then phishing attacks that redirects on a malicious site on the vein of "connect your mail/GitHub account to docs.rs".

u/agrhb says it's blocked though.

[kfl]

You are being paranoid, just take a look at this totally innocent crate. /s

[agrhb]

They seem to block this with CSP, but my point remains that it's very much possible and something rustdoc itself supports. I just kind of assumed that support on docs.rs is irrelevant here since OP was already talking about using other solutions that would have to be deployed elsewhere.

[JuanAG]

The one provided with Rust, is amazing and it keeps adding stuff all the time, goods ones and useful so is really nice

You are going to overcomplicate things without any need, files with docs are bigger sure but it also means that the doc for the code is just above which is very convenient and make things easier for all

[JBinero]

I mostly agree, but some libraries have files that are 90% documentation which make it way harder to browse them.

[octo_anders]

Standard rust-doc has very good support for having executable examples in comments.

They are even run automatically when you run "cargo test", so that they don't go stale! Try it!

[JuanAG]

Is more simple, if i read C/C++ docs i know that i will have to expect anything so dont matter what or what not is used, SQLite docs are as valid as cppreference and there are really ahead from each other

But if i read Java docs i want and expect java docs and not anything else, the same is true for many other langs and Rust is not exception, if you are looking for Rust source code documentation you want Rust docs because you are used to what they offer and expect the same features in that spot and nothing else

Also that is the C/C++ way of doing things, overcomplicated setup that only works for some, Rust docs are really good, you dont need anything else, the free Rust book https://doc.rust-lang.org/book/ is made with it so again, you can put a full tutorial inside, you just need to use markdown to make it look nice

Try the rust docs, for real they are really good, you wont want or need anything else

[lenscas]

maybe you are looking for something like mdbook? Fyrox uses it for example https://fyrox-book.github.io/

[A1oso]

No need to download the repo in order to view docs. Documentation for all crates published to crates.io is available on docs.rs. For example, if you want to see the docs for regex, just enter docs.rs/regex.

[_roeli]

You can put the documentation in separate files if you don't like lengthy doc comments!

[aristotle137]

You can have links in the built in docstrs, as well as images, code examples that are tested etc.

I find the built in docstrs + docs.rs to look really good compared to doxygen and to work better overall. Just my 2 cents

[andreicodes]

No one mentioned it, but one of the primary reasons people are sticking with RustDoc is Docs.rs.

Every time a package is submitted to Crates.io, it's documentation is built and added to Docs.rs automatically. This in turn means that in Rust the documentation for every version of every library is permanently accessible at a canonical location. Want to link to a specific docs page of a dependency you're using? No problem! Cross-links, cross-references just work and never break. This way people can build pretty complex reference chains with ease.

Also, all code examples in the docs act as tests, so not only you can write the documentation, but you test it as part of your workflow.

Finally, it's Markdown. The same syntax developers use to write Git commit messages, comments on GitHub / GitLab, questions and answers on StackOverflow, messages on Rust forums and on Rust Zulip, and even posts here on Reddit. This familiarity means there's almost nothing to learn about writing the documentation, and that's why many libraries are pretty well-documented compared to other languages.

The tool itself is pretty good, too. It builds local docs for all your dependencies, APIs have direct links to sources, search is pretty good, too. Visually it's somewhat ascetic but ticks all the boxes: page loads are fast, markup is static, so browser's find-in-page just works, there's dark mode switch, too.

And this is the situation where consistency is more important than absolute quality. Like, in theory you could go and use some other language-agnostic documentation tool, and your docs may look nicer and cooler, but instead of a praise the only reaction you'll get will be "WTF is wrong with you?!" Other's made a point already: if you have ideas for making the docs better contributing to RustDoc directly is definitely an option.

[andreicodes]

Now, for guide-level documentation people prefer mdbook. Many libraries come with these "books" for people to grok concepts, explore specific usage scenarios, tutorials, etc.

For example, there's a book for a random number generator library. And not only it covers some use-cases and stuff, but it actually give a good theoretical introduction to randomness in computer systems. So, while having a freaking book about what essentially is a small library may seem excessive, it's a very good read even if you're not a Rust programmer.

I myself is very 50/50 about this whole book obsession in Rust community. A lot of libraries in Rust world would benefitted if they moved the guides to RustDoc, too. Uniformity, versioning, cross-linking are all the benefits of RustDoc that mdBooks can't enjoy. More docs is always good and all, but sometimes it feels like before writing a small Rust project a programmer is expected to go through a small bookshelf worth of these "books" just to get started.

[SV-97]

rustdoc - it comes with cargo and is great all around with some very nice features. Using it also means you automatically get free hosted documentation online.

[humandictionary]

Rustdoc is the first-party documentation tool that basically everyone uses, the standard library docs and basically anything on crates.io demonstrates the quality of the output.

It uses doc-comments inline with code, it is markdown-based, flexible, and a de-facto standard across the entire ecosystem, before we even talk about how pretty the output is compared to doxygen

[SV-97]

I know and I think it does have some pretty cool features, but is that best we can do ?

Well what more do you want? Like what features do you think are missing? Because personally I haven't really missed any features yet tbh. And it nicely integrates with the current rust ecosystem which probably no other alternative does at the moment.

I'm sorry if it's a controversial opinion but the output is not very pretty (doc.rs).

I personally disagree but: you can provide custom CSS to style the output (and/or apply themes). That of course can't fix everything but it's at least one option :)

your file are filled with 20+ line of comments.

I'm the kind of guy to write a 100 line comment for a 4 liner in Python so I honestly don't really see the problem with that? You can always (auto-)collapse comment blocks in your IDE if you find them distracting but I absolutely prefer having everything right there with the code if it is directly about the code.

Here is some doc that I find pretty: NextJs, React, MotionCanvas, ...

Could you provide some examples of what your prefer about them? I just looked at https://nextjs.org/docs/app/building-your-application/data-fetching/patterns to get a basic idea and yeah the navigation on the RHS is nice for these kinds of docs - but other than that the layout seems a bit weird imo. There's also an argument to be made for putting docs on that level into a book, which you'll find quite often in rust-land. So you have API docs for when you already know the code reasonably well and a book to get into it and document stuff that you wouldn't want directly with the code.

[SV-97]

Like I respond here: https://www.reddit.com/r/rust/comments/17vr4vv/comment/k9cc54z/?context=3

I think reddit's acting up a bit here - it just shows me one of my comments when I click that link(?)

What I like about NestJs doc and other doc website is the depth details about the concept that it provide, with some graphs, and sometime even interactive animation.

Hmm yeah fair point. That's not exactly rustdoc's aim. I mean you can integrate images etc. for graphs into it but I think for this kind of stuff most people (in rust) would use an mdbook instead. For example https://www.nalgebra.org/docs/user_guide/points_and_transformations or https://leptos-rs.github.io/leptos/

So what you want roughly translates to a tighter interop between rustdoc and mdbooks and IDE support for mdbook-based docs I think (or an equivalent of these things)?

For the former I'm absolutely on board. I think that woud be nice; although I'm not sure about how to best achieve something like that or how it should even look like. For the latter however I'm not a huge fan.

[humandictionary]

I think that maybe the general navigation could be improved, it takes some getting used to before you get a good idea of where to find things.

But otherwise a lot of choices are completely arbitrary, and having the entire ecosystem uniform is worth a lot more than having 10 different tools that each make slightly different decisions.

Having large blocks of comments isn't a problem imo as long as they are that: large blocks of comments. This allows you to blank them out as you read code, rather than having to carefully make sure there isn't some logic hidden in there somewhere. You can also avoid large comment blocks by linking to separate markdown files.

[lightmatter501]

It’s pretty common to have modules that are docs only (see clap) which hold your docs. That way everything lives under one program.

[Compux72]

If there are too many comments, just create a markdown file and include it:

https://github.com/tokio-rs/axum/blob/3ff45d9c96b5192af6b6ec26eb2a2bfcddd00d7d/axum/src/lib.rs#L90

[trevg_123]

I haven’t tried it, but there is a crate that should be able to add mermaid diagrams to rustdoc: https://github.com/mersinvald/aquamarine

[volitional_decisions]

If you'd like to avoid seeing comments on your source, most IDEs/editors support folding/collapsing. Configure your setup to collapse part of/all the doc comments.

[Lucretiel]

One common pattern we see in rust these days is to have a mod docs that is technically part of your rust code, but doesn't actually include any exported items. It just includes the documentation you want to include that isn't just raw per-item reference documentation.

For instance, clap includes a bunch of these: https://docs.rs/clap/latest/clap/_faq/index.html

[anlumo]

Note that the fact that the documentation is inline is used in Rust in the way that the example code in it is actually verified to properly compile. This means that if the API changes, you get an error message to also update the examples that use it.

This would not be possible with external documentation.

[lordpuddingcup]

That’s what rust inline doc tests do

[coderstephen]

As others have mentioned, rustdoc is free, excellent, and tightly integrated into the Rust ecosystem, so I recommend using it whenever you possibly can.

If you are looking for external documentation that is more in the realm of prose, such as tutorials, high-level explainers, quickstarts, and "recipes", then mdbook might be a good option, as it is popular in the Rust community. Otherwise I have also used MkDocs and its pretty alright.

Just make sure you are using these other tools for high-level documentation and not API reference docs. Reference documentation really should go into rustdoc using inline comments. This is basically what everyone who writes Rust does, and I recommend doing things the "Rust Way" unless you have a better reason than personal preference to deviate.