Skip to content

Fix rustdoc link errors on rustc 1.99 and nightly - #8

Merged
SomeB1oody merged 1 commit into
masterfrom
fix/rustdoc-redundant-links
Oct 6, 2026
Merged

SomeB1oody merged 1 commit into
masterfrom
fix/rustdoc-redundant-links

Conversation

@SomeB1oody

@SomeB1oody SomeB1oody commented Oct 6, 2026 •

Copy link
Copy Markdown
Owner

Problem

The doc workflow fails on master. The workflow runs cargo doc with RUSTDOCFLAGS="-D warnings" on the latest stable toolchain. Stable moved to rustc 1.99.0 on 2026-09-28.

Rustdoc 1.99 resolves a link in a module doc (//!) in the scope of that module. An inline link such as [`Optimizer`](crate::neural_network::traits::Optimizer) then fails rustdoc::redundant_explicit_links, because the label alone resolves to the same item. Nightly (1.101) flags more of these links, so stable 1.101 will break the workflow again.

The build docs of GroupNormalization and InstanceNormalization (from #5) also link the private MIN_RANK constant. This fails rustdoc::private_intra_doc_links.

Reproduction

Run on master (403042f):

RUSTDOCFLAGS="-D warnings" cargo +1.99.0 doc --all-features --no-deps
error: public documentation for `build` links to private item `MIN_RANK`
   --> src/neural_network/layers/regularization/normalization/group_normalization.rs:255:11
    |
255 |     /// [`MIN_RANK`]
    |           ^^^^^^^^ this item is private
    |
    = note: this link will resolve properly if you pass `--document-private-items`
    = note: `-D rustdoc::private-intra-doc-links` implied by `-D warnings`

error: public documentation for `build` links to private item `MIN_RANK`
   --> src/neural_network/layers/regularization/normalization/instance_normalization.rs:254:11

error: redundant explicit link target
  |
  = note: when a link's destination is not specified,
          the label is used to resolve intra-doc links
  = note: `-D rustdoc::redundant-explicit-links` implied by `-D warnings`

error: could not document `rustyml`

Fix

  • Module docs use reference-style link definitions: [`Optimizer`] in the text and //! [`Optimizer`]: crate::neural_network::traits::Optimizer at the end of the block. All 128 inline crate-path links in 41 module docs use this form now, not only the links that 1.99 flags.
  • Removing the target alone is not correct. Rustdoc 1.89 (the MSRV in Cargo.toml) cannot resolve these labels in a module doc. The reference-style form resolves on all 3 toolchains.
  • The build docs of GroupNormalization and InstanceNormalization give the rank value (2 and 3) in place of the private link.
  • The outer doc of neural_network::error writes Error as code. The module doc of that module already links the type.

No code changes.

Rustdoc 1.99 resolves a module doc link in the scope of the module. An
inline link with a crate path then fails the redundant_explicit_links
lint. Nightly 1.101 flags more of these links. Module docs now use
reference-style link definitions. Rustdoc 1.89 (the MSRV), 1.99 and
nightly all resolve this form without a warning.

The build docs of GroupNormalization and InstanceNormalization linked
the private MIN_RANK constant. The docs now give the rank value.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@SomeB1oody
SomeB1oody merged commit 94da3c3 into master Oct 6, 2026
4 checks passed
@SomeB1oody
SomeB1oody deleted the fix/rustdoc-redundant-links branch October 6, 2026 20:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant