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

alice-i-cecile · 2021-12-30T02:16:34Z

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.

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

Run on 2023-03-14:
Crate | Docs Coverage

The text was updated successfully, but these errors were encountered:

alice-i-cecile · 2021-12-30T02:21:26Z

So, the steps to tackle this are simple enough.

Pick a crate that is small, or nearly documented.
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.
Once you've reached 100% coverage, add #!warn(missing_docs) to the start of that crate's lib.rs file.
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 · 2021-12-30T08:36:39Z

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 · 2021-12-30T19:48:17Z

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 · 2021-12-30T21:32:14Z

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

james7132 · 2021-12-31T20:39:29Z

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

ghost · 2022-01-01T19:04:39Z

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

Sheepyhead · 2022-01-01T19:21:55Z

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

Sheepyhead · 2022-01-01T19:44:55Z

I'll be looking at bevy_transform next

…3514) # Objective This contributes documentation that should cover the entirety of bevy_internal as requested in #3492 ## Solution warn(missing_docs) has been activated and documentation has been added to missing parts so that no warnings appear from this setting

Sheepyhead · 2022-01-01T21:30:46Z

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 · 2022-01-01T21:37:07Z

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.

This PR is part of the issue #3492. # Objective - Add and update the bevy_dylib documentation to achieve a 100% documentation coverage. - Add the #![warn(missing_docs)] lint to keep the documentation coverage for the future. # Solution - Add and update the bevy_dylib documentation. - Add the #![warn(missing_docs)] lint.

mockersf · 2022-01-02T13:20:03Z

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 · 2022-01-02T15:46:34Z

... 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 · 2022-01-02T16:49:38Z

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

…core and enable warning on missing docs. (#3521) This PR is part of the issue #3492. # Objective - Clean up dead code in `bevy_core`. - Add and update the `bevy_core` documentation to achieve a 100% documentation coverage. - Add the #![warn(missing_docs)] lint to keep the documentation coverage for the future. # Solution - Remove unused `Bytes`, `FromBytes`, `Labels`, and `EntityLabels` types and associated systems. - Made several types private that really only have use as internal types, mostly pertaining to fixed timestep execution. - Add and update the bevy_core documentation. - Add the #![warn(missing_docs)] lint. # Open Questions Should more of the internal states of `FixedTimestep` be public? Seems mostly to be an implementation detail unless someone really needs that fixed timestep state.

james7132 · 2022-01-02T21:02:36Z

Updated my PRs to pass the docs_markdown lints.

adsick · 2023-03-14T13:10:12Z

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 · 2023-03-14T18:15:11Z

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%

# Objective - [x] Add documentation comments to `bevy_winit` - [x] Add `#![warn(missing_docs)]` to `bevy_winit`. Relates to #3492 --------- Co-authored-by: François <mockersf@gmail.com>

targrub · 2023-04-03T18:53:56Z

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 · 2023-08-13T05:39:43Z

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.

# Objective Complete the documentation of `bevy_input` (#3492). This PR is part of a triptych of PRs : - #9467 - #9469 ## Solution Add missing documentation on items in `lib.rs`. --------- Co-authored-by: Pascal Hertleif <killercup@gmail.com>

# Objective Complete the documentation of `bevy_input` (#3492). This PR is part of a triptych of PRs : - #9467 - #9468 ## Solution Add missing documentation on items in `gamepad.rs` --------- Co-authored-by: Pascal Hertleif <killercup@gmail.com>

# Objective Complete the documentation of `bevy_input` (#3492). This PR is part of a triptych of PRs : - #9468 - #9469 ## Solution Add documentation on modules in `bevy_input`.

Kanabenki · 2023-09-28T11:25:08Z

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:

# Objective Currently the `missing_docs` lint is allowed-by-default and enabled at crate level when their documentations is complete (see #3492). This PR proposes to inverse this logic by making `missing_docs` warn-by-default and mark crates with imcomplete docs allowed. ## Solution Makes `missing_docs` warn at workspace level and allowed at crate level when the docs is imcomplete.

# Objective Currently the `missing_docs` lint is allowed-by-default and enabled at crate level when their documentations is complete (see bevyengine#3492). This PR proposes to inverse this logic by making `missing_docs` warn-by-default and mark crates with imcomplete docs allowed. ## Solution Makes `missing_docs` warn at workspace level and allowed at crate level when the docs is imcomplete.

# Objective - Some members of `bevy_dynamic_plugin` are not documented. - Part of #3492. ## Solution - Add documentation to members missing it in `bevy_dynamic_plugin`. - Update existing documentation for clarity and formatting. --- ## Changelog - Completely document `bevy_dynamic_plugin`. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: James Liu <contact@jamessliu.com>

# Objective - Some members of `bevy_dynamic_plugin` are not documented. - Part of bevyengine#3492. ## Solution - Add documentation to members missing it in `bevy_dynamic_plugin`. - Update existing documentation for clarity and formatting. --- ## Changelog - Completely document `bevy_dynamic_plugin`. --------- Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com> Co-authored-by: James Liu <contact@jamessliu.com>

alice-i-cecile added C-Docs An addition or correction to our documentation D-Trivial Nice and easy! A great choice to get started with Bevy C-Tracking-Issue An issue that collects information about a broad development initiative labels Dec 30, 2021

ghost mentioned this issue Dec 31, 2021

docs: Documentation and clean up of bevy_math. #3503

Closed

11 tasks

james7132 mentioned this issue Jan 1, 2022

[Merged by Bors] - Document bevy_tasks and enable #![warn(missing_docs)] #3509

Closed

NiklasEi mentioned this issue Jan 1, 2022

[Merged by Bors] - Complete inline documentation for bevy_audio #3510

Closed

Sheepyhead mentioned this issue Jan 1, 2022

[Merged by Bors] - Added missing docs to bevy_internal and added warn on missing docs #3514

Closed

ghost mentioned this issue Jan 1, 2022

[Merged by Bors] - Updated bevy_dylib documentation and added missing_doc warning. #3515

Closed

Sheepyhead mentioned this issue Jan 1, 2022

[Merged by Bors] - Added docs for bevy_transform #3516

Closed

This was referenced Jan 2, 2022

[Merged by Bors] - Add crate level docs to bevy_log and enable #![warn(missing_docs)] #3520

Closed

[Merged by Bors] - Remove Bytes, FromBytes, Labels, EntityLabels. Document rest of bevy_core and enable warning on missing docs. #3521

Closed

Sheepyhead mentioned this issue Jan 2, 2022

[Merged by Bors] - Partially document bevy_ui #3526

Closed

dbearden mentioned this issue Jan 3, 2022

[Merged by Bors] - Bevy app docs #3539

Closed

james7132 mentioned this issue Feb 21, 2023

Document bevy_ecs::storage #7770

Merged

beeryt mentioned this issue Mar 17, 2023

Add documentation comments to bevy_winit #8115

Merged

2 tasks

dimvoly mentioned this issue Apr 2, 2023

Accept NumpadEnter as Enter mvlabat/bevy_egui#171

Merged

alice-i-cecile mentioned this issue Aug 12, 2023

Add missing documentation to bevy_time #9428

Merged

This was referenced Aug 17, 2023

Bevy Input Docs : the modules #9467

Merged

Bevy Input Docs : lib.rs #9468

Merged

Bevy Input Docs : gamepad.rs #9469

Merged

tguichaoua mentioned this issue Aug 19, 2023

Guidelines for the crate level documentation : fixing the inconsistencies #9500

Open

Kanabenki mentioned this issue Sep 27, 2023

Fix the doc warning attribute and document remaining items for bevy_window #9933

Merged

tguichaoua mentioned this issue Feb 3, 2024

Inverse missing_docs logic #11676

Merged

BD103 mentioned this issue Feb 21, 2024

Document all members of bevy_dynamic_plugin #12029

Merged

BD103 added D-Straightforward Simple bug fixes and API improvements, docs, test and examples and removed D-Trivial Nice and easy! A great choice to get started with Bevy labels Jul 18, 2024

janhohenheim mentioned this issue Sep 5, 2024

Add module and supporting documentation to bevy_assets #15056

Merged

BenjaminBrienen mentioned this issue Sep 19, 2024

Allow to expect (adopted) #15301

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

alice-i-cecile commented Dec 30, 2021 •

edited

Loading

alice-i-cecile commented Dec 30, 2021

mfdorst commented Dec 30, 2021

alice-i-cecile commented Dec 30, 2021

ghost commented Dec 30, 2021

james7132 commented Dec 31, 2021

ghost commented Jan 1, 2022

Sheepyhead commented Jan 1, 2022

Sheepyhead commented Jan 1, 2022

Sheepyhead commented Jan 1, 2022

alice-i-cecile commented Jan 1, 2022

mockersf commented Jan 2, 2022

ghost commented Jan 2, 2022

Sheepyhead commented Jan 2, 2022

james7132 commented Jan 2, 2022

adsick commented Mar 14, 2023 •

edited

Loading

james7132 commented Mar 14, 2023

targrub commented Apr 3, 2023

JMS55 commented Aug 13, 2023

Kanabenki commented Sep 28, 2023 •

edited

Loading

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

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

Comments

alice-i-cecile commented Dec 30, 2021 • edited Loading

alice-i-cecile commented Dec 30, 2021

mfdorst commented Dec 30, 2021

alice-i-cecile commented Dec 30, 2021

ghost commented Dec 30, 2021

james7132 commented Dec 31, 2021

ghost commented Jan 1, 2022

Sheepyhead commented Jan 1, 2022

Sheepyhead commented Jan 1, 2022

Sheepyhead commented Jan 1, 2022

alice-i-cecile commented Jan 1, 2022

mockersf commented Jan 2, 2022

ghost commented Jan 2, 2022

bevy_dylib

bevy_math / bevy_ui

Sheepyhead commented Jan 2, 2022

james7132 commented Jan 2, 2022

adsick commented Mar 14, 2023 • edited Loading

james7132 commented Mar 14, 2023

targrub commented Apr 3, 2023

JMS55 commented Aug 13, 2023

Kanabenki commented Sep 28, 2023 • edited Loading

alice-i-cecile commented Dec 30, 2021 •

edited

Loading

adsick commented Mar 14, 2023 •

edited

Loading

Kanabenki commented Sep 28, 2023 •

edited

Loading