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

reference feature flags in docs #259

Merged
merged 4 commits into from
Apr 5, 2020
Merged

Conversation

robjtede
Copy link
Contributor

@robjtede robjtede commented Apr 4, 2020

Makes it clearer when browsing docs which feature flags are needed for certain features using a docsrs config flag.

Test locally using:

RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --workspace --lib --no-deps --all-features --open

eg:
2020-04-04_02 26 46-e99bc6aa

@hecrj hecrj added the improvement An internal improvement label Apr 5, 2020
@hecrj
Copy link
Member

hecrj commented Apr 5, 2020

I like the idea!

I believe it's a bit noisy when marking whole modules, as mentioned in rust-lang/rust#43781 (comment).

Maybe we could settle with a note in the module documentation for the time being, while the feature matures.

@robjtede
Copy link
Contributor Author

robjtede commented Apr 5, 2020

Yeah, honestly the reason I didnt do everything yet is incase you said that. Project like Tokio has gone ahead with this approach: https://docs.rs/tokio/0.2.16/tokio/fs/index.html, https://docs.rs/tokio/0.2.16/tokio/fs/struct.File.html.

Should do something to make the features clearer though. Did trip me up initially when starting with the canvas module. Note in the module doc would be fine, too.

@hecrj
Copy link
Member

hecrj commented Apr 5, 2020

Should do something to make the features clearer though. Did trip me up initially when starting with the canvas module. Note in the module doc would be fine, too.

Agreed. After thinking some more about it, I believe it's better to be too noisy than failing to warn our users properly. I also feel the warning blends in nicely once you get used to it. And if it's too distracting, you can always run cargo doc yourself.

So let's keep it! I added the message to the widgets in the root crate and enabled the feature flags for docs.rs. Let me know if I screwed something up!

@hecrj hecrj added this to the 0.1.1 milestone Apr 5, 2020
@robjtede robjtede marked this pull request as ready for review April 5, 2020 12:27
@robjtede
Copy link
Contributor Author

robjtede commented Apr 5, 2020

LGTM

@hecrj
Copy link
Member

hecrj commented Apr 5, 2020

Awesome. Thank you! 🥂

@hecrj hecrj merged commit ad0a6c4 into iced-rs:master Apr 5, 2020
@robjtede robjtede deleted the docs/feature-flags branch April 5, 2020 23:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
improvement An internal improvement
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants