Minimum documentation requirements for main.rs?

#1

A stand alone main.rs with no complexity, doesn’t appear to be generating the documentation in the same way as more complex programs that call other modules… or I’m confused from trying to get it to work.

main.rs which calls cargo.io crates sees the doc made for those other crates but then nothing that acknowledges the header /// or /// fn main() header detail.

I can force the main.rs header using instead //! so that the crates index.html exists, though that //! is different from the usual /// for main.rs with modules. Still, even once the main.rs header is acknowledged, the fn main() description still doesn’t appear and won’t allow the same //! fix. I don’t know, if that suggests only functions within impl are documented… but surprised if that’s the case, as I would have thought it’s useful to have all fns listed and ideally documented.

tldr; should /// not work on top a stand alone main.rs? Are fn outside impl not documented; or otherwise why do the comments for those not appear in a standalone main.rs?

#2

This is documented in The Rust Programming Language’s documentation chapter. //! documents the enclosing item instead of the next item, and is thus the officially correct way to document modules.

#3

Thanks… I note it seems docs only appear for public functions…

#4

The documentation is aimed at external users of an API, so it wouldn’t make too much sense to document private API items. Also note that you can hide a function from rustdoc via the #[doc(hidden)] attribute.

#5

Thanks.

and finally, I note that documentation doesn’t seem to suggest the versions - for the crate or the externals, which I’m surprised isn’t by default included.

#6

Why should it? This is usually handled by Cargo anyway.

#7

Ah… yes I forget that Cargo.toml is cargo specific. I was just thinking that the version of the crate could be considered to be part of the crate’s true full name.

If Cargo build --release doesn’t generate the docs, then the author might forget to update them?
I guess it won’t be changed if rustc doesn’t see the Cargo.toml.

#8

Cargo cannot upload the docs because there is no canonical location where to upload them. However, there are a few ways of automating this stuff (I actually learned about when setting up my [optional](https://github.com/llogiq/optional) crate. Look at .travis.yml for an example.

#9

[…] and finally, I note that documentation doesn’t seem to suggest the versions - for the crate or the externals, which I’m surprised isn’t by default included.

Without the intention to hijack this thread, I’d like to add that the lack of versions in the generated docs (by default) has led to plenty of confusion on my side in the past as well.
The reason is that sometimes, one will use a version for crates but look at outdated documentation, or the other way around.
To me it seems very useful to have rustdoc imprint version information into the docs.

Maybe it does it somewhere in a less obvious way ?

#10

Also

Without the intention to hijack this thread,

There’s a “Reply as Linked Topic” button on the right of posts, so you can split off a new discussion from an old one :slight_smile: