Simplify docs.rs documentation and build whole API

[hannobraun]

Currently, a lot of the API surface is missing from the documentation on docs.rs.

Please note that I can't verify that this works. From the message of one of the commits:

Please note that I don't have a way to test this, so I can't guarantee
it'll work. But the documentation currently builds with all features
(which is verified in [#178]), and the documentation on docs.rs
metadata seems clear enough: https://docs.rs/about/metadata

[jamesmunns]

I think this is used for gating some kind of docs-rs feature display

and https://github.com/jamesmunns/postcard/blob/bee7f0f965362e4ac687a2721d81f916e78735b1/source/postcard/src/lib.rs#L75-L106 are examples

I don't entirely recall how this works though, I probably copy and pasted it from postcard or similar.

Tho looking at https://github.com/jamesmunns/postcard/pull/108/files, we might be missing the second half of this, e.g. #[cfg_attr(doc_cfg, doc(cfg(feature = "alloc")))]. I'd prefer to keep this in and actually go fix the other missing half.

[hannobraun]

Ah, okay, I didn't consider that it actually should be used. I just saw that it isn't, and figured its some copy/paste remnant 😅

I'll look into this! But first, I'd like to dump some research here, so there's a more complete picture for later reference.

• Here's the documentation of #[doc]: https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html
• Thought the doc(cfg( syntax is unstable, documented separately: https://doc.rust-lang.org/unstable-book/language-features/doc-cfg.html
• And it seems that docs.rs is using nightly to build documentation, which is why that works.

[hannobraun]

I started looking into how to do this properly, but hit an obstacle that goes a bit beyond what I want to invest in this pull request right now. I'll document my approach and the obstacle here, in case anybody wants to pick up where I left off.

Here's the configuration I added to Cargo.toml (both of them):

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

This should make sure that documentation is generated for all code, and sets the stage for also documenting which features need to be enabled, as per the comments in this review.

To test my changes, I was trying to use this command, to mimick what docs.rs would do:

RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features

In theory, this should generate the full documentation, but without any information about features. From here, you could start documenting the features (again, as per these comments), as required.

However, when running the above command, I get an error:

error[E0557]: feature has been removed
 --> /home/hanno/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/mutex-traits-1.0.0/src/lib.rs:4:38
  |
4 | #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
  |                                      ^^^^^^^^^^^^ feature has been removed
  |
  = note: removed in 1.92.0; see <https://github.com/rust-lang/rust/pull/138907> for more information
  = note: merged into `doc_cfg`

error: Compilation failed, aborting rustdoc

For more information about this error, try `rustc --explain E0557`.
error: could not document `mutex-traits`

This is a bit more than I want to get into right now, so I've opened tosc-rs/scoped-mutex#26 and will leave it at that.

I recommend merging this pull request as-is and open an issue to track further improvements, for these reasons:

• Right now, the documentation on docs.rs is simply incomplete, and this, in my opinion, is the most important thing to fix.
• Not having unused configuration is better than having it, I think, even if using it would be even better. Adding it back would be no problem in any case.
• The documentation will show items without documenting which features are needed to enable them, which will be confusing. I consider that a smaller problem than not having complete documentation though, which is why I suggest tracking this in an issue.