BurntSushi / BurntSushi/bstr

Intradoc links are broken when building with no default features

Open
#162 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

question
Dominant language
Rust
Stars
1.1k
Forks
77
PR merge metrics
No merged PRs in 30d

Description

bstr has errors building documentation when doing so with --no-default-features.

$ cargo doc --no-default-features
warning: unresolved link to `ByteVec::unescape_bytes`
    --> src/ext_slice.rs:2783:40
     |
2783 |     /// The dual of this function is [`ByteVec::unescape_bytes`].
     |                                        ^^^^^^^^^^^^^^^^^^^^^^^ no item named `ByteVec` in scope
     |
     = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default

warning: unresolved link to `BString`
    --> src/ext_slice.rs:2786:42
     |
2786 |     /// implementation on [`BStr`] and [`BString`]. The `Debug` implementations
     |                                          ^^^^^^^ no item named `BString` in scope
     |
     = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: `bstr` (lib doc) generated 2 warnings
    Finished dev [unoptimized + debuginfo] target(s) in 0.03s

Additionally, the vast majority of intra-doc linking in this crate is hardcoding links to HTML pages that rustdoc generates. Linking in this way prevents rustdoc from properly linting whether the items being referenced exist (which is especially nice in the presence of conditional compilation).

https://github.com/BurntSushi/bstr/blob/b3cab1905c46ad7de78a032a61eef0437ed7fb58/src/lib.rs#L338-L354

Example links that are broken are this link to BString on the BStr type docs:

Screenshot 2023-06-04 at 12 16 42 AM

I've found adding this env var to CI and building the docs as part of the CI steps that test the feature matrix to be useful in preventing regressions here:

RUSTDOCFLAGS="-D warnings -D rustdoc::broken_intra_doc_links --cfg docsrs"

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running cargo doc --no-default-features with the reported RUSTDOCFLAGS to reproduce the warnings in src/ext_slice.rs. Review the hardcoded HTML links in src/lib.rs around lines 338-354 and the related documentation links, then update the links so rustdoc can validate them across feature configurations. Done means the feature-matrix documentation build produces no broken intra-doc link warnings.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
ci-cd, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.