From 506642744c1839b76e3286b6885c467d80bdc71a Mon Sep 17 00:00:00 2001 From: KDecay Date: Wed, 2 Feb 2022 21:47:29 +0000 Subject: [PATCH] docs: Fix private doc links and enable CI test (#3743) # Objective Fixes #3566 ## Solution - [x] Fix broken links in private docs. - [x] Add the `--document-private-items` flag to the CI. ## Note The following was said by @killercup in #3566: > I don't have time to confirm this but I assume that linking to private items throws an error/warning when just running cargo doc, and --document-private-item might actually hide that warning. So to test this, you'd have to run it twice. I tested this and this is thankfully not the case. If you are linking to a private item you will get a warning no matter if you run `cargo doc` or `cargo doc --document-private-items`. ### Example I added `struct Test;` to `bevy_core/src/name.rs` and linked to it inside of a doc comment using ``[`Test`]``. After that I ran `cargo doc -p bevy_core --document-private-items` using `RUSTDOCFLAGS="-D warnings"` and got the following output (note the last sentence): ```rust error: public documentation for `Name` links to private item `Test` --> crates/bevy_core/src/name.rs:11:82 | 11 | /// Component used to identify an entity. Stores a hash for faster comparisons [`Test`] | ^^^^ this item is private | = note: `-D rustdoc::private-intra-doc-links` implied by `-D warnings` = note: this link resolves only because you passed `--document-private-items`, but will break without ``` --- .github/workflows/ci.yml | 2 +- crates/bevy_ecs/src/query/iter.rs | 4 ++-- crates/bevy_ecs/src/world/mod.rs | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e57e51883d..0ca71c2f32 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -273,7 +273,7 @@ jobs: - name: Installs cargo-deadlinks run: cargo install --force cargo-deadlinks - name: Build and check doc - run: RUSTDOCFLAGS='-D warnings' cargo doc --workspace --all-features --no-deps + run: RUSTDOCFLAGS='-D warnings' cargo doc --workspace --all-features --no-deps --document-private-items - name: Checks dead links run: cargo deadlinks --dir target/doc/bevy continue-on-error: true diff --git a/crates/bevy_ecs/src/query/iter.rs b/crates/bevy_ecs/src/query/iter.rs index ad1219f683..7e135c7808 100644 --- a/crates/bevy_ecs/src/query/iter.rs +++ b/crates/bevy_ecs/src/query/iter.rs @@ -35,7 +35,7 @@ where /// This does not check for mutable query correctness. To be safe, make sure mutable queries /// have unique access to the components they query. /// This does not validate that `world.id()` matches `query_state.world_id`. Calling this on a `world` - /// with a mismatched [`WorldId`] is unsound. + /// with a mismatched [`WorldId`](crate::world::WorldId) is unsound. pub(crate) unsafe fn new( world: &'w World, query_state: &'s QueryState, @@ -175,7 +175,7 @@ where /// This does not check for mutable query correctness. To be safe, make sure mutable queries /// have unique access to the components they query. /// This does not validate that `world.id()` matches `query_state.world_id`. Calling this on a - /// `world` with a mismatched [`WorldId`] is unsound. + /// `world` with a mismatched [`WorldId`](crate::world::WorldId) is unsound. pub(crate) unsafe fn new( world: &'w World, query_state: &'s QueryState, diff --git a/crates/bevy_ecs/src/world/mod.rs b/crates/bevy_ecs/src/world/mod.rs index c07892a352..24e302ade4 100644 --- a/crates/bevy_ecs/src/world/mod.rs +++ b/crates/bevy_ecs/src/world/mod.rs @@ -1087,7 +1087,7 @@ impl World { } } - /// Empties queued entities and adds them to the empty [Archetype]. + /// Empties queued entities and adds them to the empty [Archetype](crate::archetype::Archetype). /// This should be called before doing operations that might operate on queued entities, /// such as inserting a [Component]. pub(crate) fn flush(&mut self) {