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

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% (#3509)
  • bevy_derive | 33%
  • bevy_macro_utils | 28.6%
  • bevy_math | 100.0% (#3503 | #4591)
  • bevy_app | 100.0% (#3539)
  • bevy_ecs_macros | 40.0%
  • bevy_dynamic_plugin | 42.9%
  • bevy_window | 97.8% (#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% (https://github.com/bevyengine/bevy/pull/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) (#3515)
  • bevy_text | 35.8%
  • errors | 66.7%
  • bevy_internal | 100.0% (#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%

About this issue

  • Original URL
  • State: open
  • Created 3 years ago
  • Reactions: 2
  • Comments: 26 (22 by maintainers)

Commits related to this issue

Most upvoted comments

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.

+4
mockersf on Jan 2, 2022

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:

+2
Kanabenki on Oct 5, 2023

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

+2
ghost on Dec 30, 2021

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.

+1
JMS55 on Aug 13, 2023

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.

+1
targrub on Apr 3, 2023

I’m documenting bevy_window.

+1
x-52 on Mar 25, 2022

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

+1
NiklasEi on Jan 12, 2022

I’m going to take care of bevy_input.

+1
ghost on Jan 12, 2022

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

+1
Sheepyhead on Jan 1, 2022

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

+1
Sheepyhead on Jan 1, 2022

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

+1
ghost on Jan 1, 2022
Read more comments on GitHub
← bevy: thread 'main' panicked at 'Unable to find a GPU! Make sure you have installed required drivers!'
bevy: triggering state transition from player input locks the game →