Need guidance on how to document cargo features

[brson]

Today figuring out what cargo features exist and what they do generally means navigating the project source and inspecting the toml file. That's a pretty bad experience. Need a standard way to expose this information.

[dtolnay]

One option is what I do in Serde - document them in Cargo.toml. Though we also have a page on the website so there is some duplication.

Maybe rustdoc would be more appropriate? This could also be a feature request for rustdoc: generate documentation for features using comments in Cargo.toml.

Definitely rustdoc should mention what features need to be enabled to get a particular API. If I am looking at rustdoc of a function, right there it should say this function requires feature so-and-so.

[budziq]

Hi I wanted to post directly on libz blitz thread but I see that this feature is already open.

While working on rust-lang/log#125 I've discovered that log makes an arguably insufficient attempt to document its "crate feature flags" in master:

• "Features" headline is ambiguous. I find ndarray's "crate feature flags" much clearer
• actual feature names are not mentioned in crate level docs (just wildcarded max_level_* and release_max_level_*)
• max_level_trace and release_max_level_trace are never mentioned in docs at all and cannot be discovered without inspecting the source code

Some crates like ndarray make a stellar job of documenting the "crate feature flags".

I would suggest using ndarray's approach with rustdoc as a template (even if this information would be discoverable via Cargo.toml). Imho documenting all (default and optional) feature flags with their consequences should be required. This might be handled on docs.rs side with gathering the information into a separate page.

[droundy]

Any progress on this? I'd love to see it easier to find out what features might interest me when I look at a given crate, and I'd like to be able to provide this information in my own documentation (with maximal automatic checking).

[najamelan]

This would be great...

Definitely rustdoc should mention what features need to be enabled to get a particular API. If I am looking at rustdoc of a function, right there it should say this function requires feature so-and-so.

Maybe rustdoc could pick up on #/// in toml? That way people can document in place, yet rustdoc could add a section Features immediately below crate level description... With links to a page for each feature which could show what apis require this feature?

[jyn514]

Docs.rs recently started displaying these in the 'feature flags' section: https://docs.rs/crate/bytecheck/0.2.0/features

[TrentDaniel]

I'm not sure if I'm being pedantic, or if this is actually a bug, but it seems like the general html/css format for crates on docs.rs changes once you click on the feature flags tab, and possibly others, I didn't check. There's also a curious difference between the URL for the main crate page and the feature flags page. You can see the difference between the main page, here: https://docs.rs/bytecheck/0.7.0/bytecheck/; and the feature flags page, here: https://docs.rs/crate/bytecheck/0.7.0/features. Also, if you click the feature flags tab, and then try to click the 'crate' tab, you're redirected to https://docs.rs/crate/bytecheck/0.7.0. The html/css for that page is the same style as for the feature flags page, even though I would expect it to be consistent with the initial landing page for the crate.

Is this difference in html/css intentional, or is it actually a bug?

[jyn514]

/bytecheck is generated by rustdoc; /crate/bytecheck is generated by docs.rs itself. The difference in URLs is intentional. I'm not sure exactly what you're referring to with the difference in HTML/CSS, but feel free to report an issue on rust-lang/docs.rs - let's not keep pinging this discussion though.

[ogoffart]

I made a crate for documenting the feature as comments in the Cargo.toml: https://docs.rs/document-features

[1oglop1]

This should be part of the standard distribution.

As a newcomer, I need to spend hours digging for information about features I need from the crate
EG. https://docs.rs/crate/time/0.3.24/features - crazy amount of features, and this list is just useless to me if I do not know much about the library

[sassman]

/cc @GuillaumeGomez

This would be a nice rustdoc feature, I guess.

[GuillaumeGomez]

Please open an issue for that (I didn't check if there is one open for this already or not though). Please note that it will also need the cargo team to be involved as cargo will need to provide this information to rustdoc (through command line arguments very likely).

[ranger-ross]

There is a related RFC for adding feature docs in Cargo.toml.
See rust-lang/rfcs#3485