Tracking issue: deny missing docs, one crate at a time

[alice-i-cecile]

Docs are great! However, it's easy to let them atrophy.

As Bevy grows and stabilizes, we want to be able to turn on #![warn(missing_docs)] (which will cause CI to fail if violated). This is helpful because it helpful for new users and contributors, and ensures that our code base's documentation state doesn't regress.

However, not everything is stable or well documented enough to do so already. We should turn this on one crate at a time, once it hits 100% coverage. If there's a crate

Let's check the current doc coverage.

1. Set the following environment variable (on Windows, I used the $Env: syntax): RUSTDOCFLAGS="-Z unstable-options --show-coverage"
2. Run cargo +nightly doc --workspace --all-features --no-deps

Run on 2022-03-02: Crate | Docs Coverage

• [ ] bevy_utils | 53.3%
• [x] bevy_tasks | 100.0% (#3509)
• [ ] bevy_derive | 33%
• [ ] bevy_macro_utils | 18.2%
• [ ] bevy_math | 33.3% (#3503 | #4591)
• [x] bevy_app | 100.0% (#3539)
• [ ] bevy_ecs_macros | 18.2%
• [ ] bevy_dynamic_plugin | 50%
• [ ] bevy_window | 17.8% (#4333)
• [x] bevy_crevice | 100% (Not our problem)
• [x] bevy_log | 100.0%
• [ ] bevy_transform | 100.0%
• [x] bevy_core | 100.0%
• [ ] bevy_reflect| 52.2%
• [ ] bevy_input | 17.6% (Claimed by @KDecay)
• [ ] bevy_gilrs | 0%
• [ ] bevy_diagnostic | 50%
• [ ] bevy_winit | 16.7%
• [ ] bevy_audio | 100.0%
• [ ] bevy_scene | 10%
• [ ] bevy_asset | 27.8% (https://github.com/bevyengine/bevy/pull/3536)
• [ ] bevy_core_pipeline | 3.4%
• [ ] bevy_gltf | 21.9%
• [ ] bevy_sprite | 33.3%
• [ ] bevy_ecs | 50.8%
• [x] bevy_dylib | 100% (warning not yet enabled) (#3515)
• [ ] bevy_text | 15.9%
• [ ] errors | 66.7%
• [x] bevy_internal | 100.0% (#3514)
• [ ] bevy_pbr | 23.2%
• [ ] bevy_ui | 75.5%
• [ ] bevy_render | 35.9%

[alice-i-cecile]

So, the steps to tackle this are simple enough.

1. Pick a crate that is small, or nearly documented.
2. Make a PR to finish documenting the crate. If the crate is large, this needs to be split across several PRs to make reviewing easier.
3. Once you've reached 100% coverage, add #!warn(missing_docs) to the start of that crate's lib.rs file.
4. Repeat 20 or so times.

If you're looking for good candidates, I think the low-hanging fruit here is:

• bevy_utils
• bevy_tasks
• bevy_math
• bevy_app
• bevy_dynamic_plugin
• bevy_log
• bevy_core
• bevy_gilrs
• bevy_transform
• bevy_internal`

plus the crates that are already at 100% coverage. Feel free to ping me if you would like review or help understanding the code.

[mfdorst]

Does it make sense to add that to bevy_crevice since it's really on the crevice maintainers to keep their docs up to date?

[alice-i-cecile]

Does it make sense to add that to bevy_crevice since it's really on the crevice maintainers to keep their docs up to date?

Yeah, I agree with you, since we're basically just mirroring it.

[ghost]

I'm going to document the bevy_math crate and will link the PR here once I'm done.

[james7132]

Mentioned this on Discord, but I'll take on bevy_tasks.

[ghost]

I'm going to add the warning to bevy_dylib and update the documentation if needed.

[Sheepyhead]

I'll be adding the warning to bevy_internal and adding missing docs

[Sheepyhead]

I'll be looking at bevy_transform next

[Sheepyhead]

I'll take a look at bevy_ui but I make no promises, I think there are parts of this crate I cannot explain yet

[alice-i-cecile]

I'll take a look at bevy_ui but I make no promises, I think there are parts of this crate I cannot explain yet

Sounds good, it's a big crate so even partial progress there will be very helpful.

[mockersf]

For the people with ongoing doc PRs (@Sheepyhead, @james7132, @KDecay, @NiklasEi I think?), could you check your PR with the clippy lint clippy::doc_markdown?

It should be enabled soon, there was a first pass to fix issues but it's not yet finished, check #3457 for more details. It could be painful to re-introduce issues.

[ghost]

... could you check your PR with the clippy lint clippy::doc_markdown?

bevy_dylib

I just checked this for my PR #3515 that updated the documentation of bevy_dylib. I ran the following command without any errors:

cargo clippy -p bevy_dylib --no-deps --all-targets --all-features -- -D warnings -A clippy::type_complexity -W clippy::doc_markdown

bevy_math / bevy_ui

I also have the PR #3503 that is not completely done yet and updates the documentation of bevy_math and parts of bevy_ui. I will run the following commands when the PR is ready from my end:

cargo clippy -p bevy_math --no-deps --all-targets --all-features -- -D warnings -A clippy::type_complexity -W clippy::doc_markdown

cargo clippy -p bevy_ui --no-deps --all-targets --all-features -- -D warnings -A clippy::type_complexity -W clippy::doc_markdown

[Sheepyhead]

could you check your PR with the clippy lint clippy::doc_markdown

For the record I find this lint extremely obvoxious, as it assumes anything in a doc with CamelCase is supposed to be backticked

[james7132]

Updated my PRs to pass the docs_markdown lints.

[Sheepyhead]

Updated my PRs to pass the docs_markdown lints.

I have also done this

[ghost]

I'm going to take care of bevy_input.

[NiklasEi]

@alice-i-cecile could you update the issue description?

[x-52]

I'm documenting bevy_window.

[x-52]

Uh oh... For some reason, GitHub will close this issue when my PR merges, but we haven't documented all of bevy yet!

[alice-i-cecile]

Uh oh... For some reason, GitHub will close this issue when my PR merges, but we haven't documented all of bevy yet!

Doesn't look like it right now; it doesn't show up in the Linked Issues tab. IIRC "Fixes" and "Closes" are both magic words that trigger that. In any case, we can just reopen this if it gets closed by mistake :)

[x-52]

Okay, Thanks!

[adsick]

there is a missing "Safety" doc in DynamicPluginExt: https://github.com/bevyengine/bevy/blob/520e413c219494b3158ecbdf2b69a786a8469819/crates/bevy_dynamic_plugin/src/loader.rs#LL36C17-L36C17

[james7132]

Updating the table we have on the current status of this issue:

Crate	Doc Coverage
bevy_a11y	100%
bevy_animation	100%
bevy_app	100%
bevy_asset	100%
bevy_audio	100%
bevy_core_pipeline	22.3%
bevy_core	100%
bevy_derive	57.1%
bevy_diagnostic	50%
bevy_dylib	100%
bevy_dynamic_plugin	42.9%
bevy_ecs_macros	40%
bevy_ecs	79.5%
bevy_encase_derive	0%
bevy_gilrs	0%
bevy_gltf	16.7%
bevy_hierarchy	100%
bevy_input	90.6%
bevy_internal	100%
bevy_log	100%
bevy_macro_utils	28.6%
bevy_math	100%
bevy_mikktspace	90%
bevy_pbr	37.4%
bevy_ptr	100%
bevy_reflect_derive	88.9%
bevy_reflect	61.7%
bevy_render_macros	25%
bevy_render	48.2%
bevy_scene	22.1%
bevy_sprite	30.8%
bevy_tasks	100%
bevy_text	35.8%
bevy_time	78.8%
bevy_transform	100%
bevy_ui	74.8%
bevy_utils_macros	0%
bevy_utils	100%
bevy_window	97.8%
bevy_winit	56%

[targrub]

Taking the first crate on the list currently missing documentation, bevy_core_pipeline, my best judgement (based mostly on those who originally checked in the code in its present location) is that those most familiar with the code, and thus best situated to add the requested documentation, are the following: @cart -- crates/bevy_core_pipeline/src/blit/mod.rs crates/bevy_core_pipeline/src/clear_color.rs crates/bevy_core_pipeline/src/core_2d/camera_2d.rs crates/bevy_core_pipeline/src/core_2d/main_pass_2d_node.rs crates/bevy_core_pipeline/src/core_2d/mod.rs crates/bevy_core_pipeline/src/core_3d/camera_3d.rs crates/bevy_core_pipeline/src/core_3d/main_opaque_pass_3d_node.rs crates/bevy_core_pipeline/src/core_3d/main_transparent_pass_3d_node.rs crates/bevy_core_pipeline/src/core_3d/mod.rs crates/bevy_core_pipeline/src/lib.rs crates/bevy_core_pipeline/src/msaa_writeback.rs @JMS55 -- crates/bevy_core_pipeline/src/bloom/mod.rs crates/bevy_core_pipeline/src/bloom/settings.rs crates/bevy_core_pipeline/src/taa/mod.rs @Elabajaba -- crates/bevy_core_pipeline/src/contrast_adaptive_sharpening/mod.rs crates/bevy_core_pipeline/src/contrast_adaptive_sharpening/node.rs @jakobhellermann -- crates/bevy_core_pipeline/src/fullscreen_vertex_shader/mod.rs crates/bevy_core_pipeline/src/tonemapping/mod.rs crates/bevy_core_pipeline/src/tonemapping/node.rs crates/bevy_core_pipeline/src/upscaling/mod.rs crates/bevy_core_pipeline/src/upscaling/node.rs @DGriffin91 -- crates/bevy_core_pipeline/src/fxaa/mod.rs crates/bevy_core_pipeline/src/fxaa/node.rs @IceSentry -- crates/bevy_core_pipeline/src/prepass/mod.rs crates/bevy_core_pipeline/src/prepass/node.rs

My apologies if any my guesses were wrong.

[JMS55]

My plan is to get to renderer documentation (bevy_render, bevy_core_pipeline, bevy_pbr) sometime soon. I have a couple of open PRs I want to resolve first though.

[Kanabenki]

As I started taking a shot a completing the docs for some of the crates, I thought it would be good to have some updated info on the global documentation progress. I only added PR links for those that added the warn(missing_doc) attribute once a crate doc was complete. Here's what I got:

• [x] bevy_a11y | 100.0% | (https://github.com/bevyengine/bevy/pull/6874)
• [x] bevy_animation | 100.0% | (https://github.com/bevyengine/bevy/pull/4375)
• [x] bevy_utils | 100.0% (https://github.com/bevyengine/bevy/pull/6897)
• [x] bevy_tasks | 100.0% (https://github.com/bevyengine/bevy/pull/3509)
• [ ] bevy_derive | 57.1%
• [ ] bevy_macro_utils | 35.7%
• [x] bevy_math | 100.0% (https://github.com/bevyengine/bevy/pull/3503 | https://github.com/bevyengine/bevy/pull/4591)
• [x] bevy_app | 100.0% (https://github.com/bevyengine/bevy/pull/3539)
• [ ] bevy_ecs_macros | 36.4%
• [ ] bevy_dynamic_plugin | 42.9%
• [x] bevy_window | 100.0% (https://github.com/bevyengine/bevy/pull/4333) | (https://github.com/bevyengine/bevy/pull/9933)
• [x] bevy_crevice | 100% (Not our problem)
• [x] bevy_log | 100.0% | (https://github.com/bevyengine/bevy/pull/3520)
• [x] bevy_transform | 100.0% | (https://github.com/bevyengine/bevy/pull/3516)
• [x] bevy_core | 100.0% | (https://github.com/bevyengine/bevy/pull/3521)
• [ ] bevy_reflect| 71.1%
• [x] bevy_input | 100.0% | (https://github.com/bevyengine/bevy/pull/9467)
• [x] bevy_gilrs | 100.0% | (https://github.com/bevyengine/bevy/pull/10010)
• [ ] bevy_diagnostic | 52.2%
• [x] bevy_winit | 100.0% | (https://github.com/bevyengine/bevy/pull/8115)
• [x] bevy_audio | 100.0% | (https://github.com/bevyengine/bevy/pull/3510)
• [x] bevy_scene | 100.0% | (https://github.com/bevyengine/bevy/pull/9949)
• [ ] bevy_asset | 64.5% | (seems like this one regressed from 100%)
• [ ] bevy_asset_macros | 0.0%
• [ ] bevy_core_pipeline | 26.3%
• [x] bevy_gltf | 100.0% | (https://github.com/bevyengine/bevy/pull/9998)
• [ ] bevy_sprite | 28.8%
• [x] bevy_ecs | 100.0% | (https://github.com/bevyengine/bevy/pull/8731)
• [x] bevy_dylib | 100% (warning not yet enabled) (https://github.com/bevyengine/bevy/pull/3515)
• [ ] bevy_text | 34.9%
• [ ] errors | 80.0%
• [x] bevy_internal | 100.0% (https://github.com/bevyengine/bevy/pull/3514)
• [ ] bevy_pbr | 39.2%
• [ ] bevy_ui | 79.9%
• [ ] bevy_render | 51.2%
• [ ] bevy_core_pipeline | 22.3%
• [ ] bevy_derive | 57.1%
• [ ] bevy_encase_derive | 0%
• [x] bevy_hierarchy | 100% | (https://github.com/bevyengine/bevy/pull/4168)
• [x] bevy_log | 100%
• [ ] bevy_mikktspace | 90%
• [x] bevy_ptr | 100% | (https://github.com/bevyengine/bevy/pull/4760)
• [ ] bevy_reflect_derive| 90.9%
• [ ] bevy_render_macros | 25%
• [x] bevy_time | 100.0% | (https://github.com/bevyengine/bevy/pull/9428)
• [ ] bevy_utils_macros | 50.0%
• [x] bevy_gizmos | 100.0% | (https://github.com/bevyengine/bevy/pull/8186)