Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document items behind feature flags #22

Closed
taralx opened this issue Dec 2, 2019 · 5 comments
Closed

Document items behind feature flags #22

taralx opened this issue Dec 2, 2019 · 5 comments

Comments

@taralx
Copy link

@taralx taralx commented Dec 2, 2019

https://docs.rs/crate/mundane/0.4.2/builds

[INFO] [stderr]  Documenting mundane v0.4.2 (/opt/rustwide/workdir)
[INFO] [stderr] error: `[RsaPkcs1v15]` cannot be resolved, ignoring it...
[INFO] [stderr]    --> src/public/rsa/mod.rs:363:26
[INFO] [stderr]     |
[INFO] [stderr] 363 | /// feature is enabled, [`RsaPkcs1v15`].
[INFO] [stderr]     |                          ^^^^^^^^^^^^^ cannot be resolved, ignoring
[INFO] [stderr]     |

========

Edit by @joshlf : This issue is now about both fixing this issue and also about documenting all items behind feature flags in general; see this comment below.

@joshlf

This comment has been minimized.

Copy link
Member

@joshlf joshlf commented Dec 10, 2019

This seems like a good candidate for the new #[cfg(doc)] - we can do #[cfg(any(doc, feature))] where we used to do #[cfg(feature)] in order to make sure that everything is documented and these links always work. We should probably also update module- and item-level documentation to clarify which ones are only available behind a certain feature flag. E.g., the documentation for the bytes module could be updated from this:

//! Byte manipulation.

...to this:

//! Byte manipulation.
//!
//! *This module is available if Mundane is built with the `bytes` feature.*
@joshlf joshlf changed the title docs.rs build failing Document items behind feature flags Dec 10, 2019
@subhojit777

This comment has been minimized.

Copy link
Contributor

@subhojit777 subhojit777 commented Dec 13, 2019

Hey @joshlf I was looking into it. I couldn't replicate the problem that is mentioned. I have rustc 1.39.0 and did cargo build, but it ran without any errors. Also, tried with nightly - as per the logs here https://docs.rs/crate/mundane/0.4.2/builds/189489, but still no error. Am I missing anything? I ran build from the project root.

@joshlf

This comment has been minimized.

Copy link
Member

@joshlf joshlf commented Dec 13, 2019

It'll be cargo doc that should fail. Try that?

@subhojit777

This comment has been minimized.

Copy link
Contributor

@subhojit777 subhojit777 commented Dec 16, 2019

I have created this init PR https://fuchsia-review.googlesource.com/c/mundane/+/348889. I contains the fix of the cargo doc error. I will have to update the documentation.

@subhojit777

This comment has been minimized.

Copy link
Contributor

@subhojit777 subhojit777 commented Dec 17, 2019

@joshlf Please ignore the previous PR https://fuchsia-review.googlesource.com/c/mundane/+/348889. Here is a new one containing all the requested changes https://fuchsia-review.googlesource.com/c/mundane/+/349548 Please check this one.

@joshlf joshlf closed this in 75e11d5 Jan 19, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.