Skip to content

Documentation at docs.rs does not specify required crate features #486

Closed
@ColinFinck

Description

@ColinFinck

I just looked up https://docs.rs/uefi/0.16.0/uefi/table/boot/struct.BootServices.html#method.find_handles and was surprised to find out that my imported uefi crate didn't have a find_handles function. I had to look into the source code to realize that find_handles is only available when the "exts" feature is enabled.

docs.rs supports a syntax to specify the required features and make them part of the public documentation. An example is https://docs.rs/ntfs/0.2.0/ntfs/struct.NtfsTime.html#impl-TryFrom%3COffsetDateTime%3E

Steps required:

  1. Add a package.metadata.docs.rs section to Cargo.toml like https://github.com/ColinFinck/ntfs/blob/b0058b9b9a19bd6727a8be7ef603d1e4421255ed/Cargo.toml#L40-L42
  2. Enable the doc_cfg feature for the newly added docsrs argument: https://github.com/ColinFinck/ntfs/blob/b0058b9b9a19bd6727a8be7ef603d1e4421255ed/src/lib.rs#L37
  3. Add a corresponding cfg_attr for every cfg(feature(...)) attribute: https://github.com/ColinFinck/ntfs/blob/b0058b9b9a19bd6727a8be7ef603d1e4421255ed/src/time.rs#L36

This works at least for impls and fns. I had no luck putting this in front of a pub use clause, but this shouldn't be necessary here anyway.

Would be great to see that in the next version of uefi-rs on docs.rs :)

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions