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 2023-03-14:
Crate | Docs Coverage

• bevy_a11y | 100.0%
• bevy_animation | 100.0%
• bevy_utils | 53.3%
• bevy_tasks | 100.0% ([Merged by Bors] - Document bevy_tasks and enable #![warn(missing_docs)] #3509)
• bevy_derive | 33%
• bevy_macro_utils | 28.6%
• bevy_math | 100.0% (docs: Documentation and clean up of bevy_math. #3503 | [Merged by Bors] - Document bevy_math #4591)
• bevy_app | 100.0% ([Merged by Bors] - Bevy app docs #3539)
• bevy_ecs_macros | 40.0%
• bevy_dynamic_plugin | 42.9%
• bevy_window | 97.8% ([Merged by Bors] - Add documentation comments to bevy_window #4333)
• bevy_crevice | 100% (Not our problem)
• bevy_log | 100.0%
• bevy_transform | 100.0%
• bevy_core | 100.0%
• bevy_reflect| 61.7%
• bevy_input | 90.6% (Claimed by @KDecay)
• bevy_gilrs | 0%
• bevy_diagnostic | 50%
• bevy_winit | 56%
• bevy_audio | 100.0%
• bevy_scene | 22.1%
• bevy_asset | 100.0% ([Merged by Bors] - docs: Full documentation for bevy_asset #3536)
• bevy_core_pipeline | 3.4%
• bevy_gltf |16.7%
• bevy_sprite | 30.8%
• bevy_ecs | 79.5%
• bevy_dylib | 100% (warning not yet enabled) ([Merged by Bors] - Updated bevy_dylib documentation and added missing_doc warning. #3515)
• bevy_text | 35.8%
• errors | 66.7%
• bevy_internal | 100.0% ([Merged by Bors] - Added missing docs to bevy_internal and added warn on missing docs #3514)
• bevy_pbr | 37.4%
• bevy_ui | 74.8%
• bevy_render | 48.2%
• bevy_core_pipeline | 22.3%
• bevy_derive | 57.1%
• bevy_encase_derive | 0%
• bevy_hierarchy | 100%
• bevy_log | 100%
• bevy_mikktspace | 90%
• bevy_ptr | 100%
• bevy_reflect_derive| 88.9%
• bevy_render_macros | 25%
• bevy_time | 78.8%
• bevy_utils_macros | 0%

[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.

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.

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