ci: fix broken intra-doc links (Documentation lane)#84
Conversation
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 7 minutes and 55 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (6)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Code Review
This pull request simplifies documentation by removing several intra-doc links across the codebase, specifically in the git and auth modules. A suggestion was made to use a public re-export for a link in the auth module instead of reverting to plain text, which preserves documentation utility while still resolving link warnings.
| /// Wraps the lower-level resolver (which returns an [`AuthInfo`] diagnostic | ||
| /// record) and adds: |
There was a problem hiding this comment.
Instead of downgrading to plain text, you can link to the public re-export resolve_auth_info which is available in this module. This maintains the utility of the documentation while resolving the intra-doc link warning.
| /// Wraps the lower-level resolver (which returns an [`AuthInfo`] diagnostic | |
| /// record) and adds: | |
| /// Wraps the lower-level [`resolve_auth_info`] (which returns an | |
| /// [`AuthInfo`] diagnostic record) and adds: |
5eddc9e to
b3c75d3
Compare
Two classes of failures were blocking the Documentation lane: 1. Unresolved links in shipper-types. The outer `/// Storage backend ...` doc comment on `pub mod storage` was being merged with the module's inner `//!` docs, and rustdoc then tried to resolve the module's `[CloudStorageConfig]` / `[StorageType]` links in the parent crate scope where those items are not visible. Removing the redundant outer doc lets the module's own inner docs resolve correctly. 2. Private intra-doc links from public items. Several facades in shipper::git and shipper::auth used rustdoc links (`[super::bin_override:: local_is_git_clean]`, `[credentials::token_from_credentials_file_extended]`, `[crate::ops::git]`, etc.) that point at pub(crate) items. Those links only resolved because CI runs with --document-private-items, and rustdoc emits errors under -D warnings. Downgrade them to plain backtick code spans so the prose still reads the same but rustdoc is happy either way. No public-API changes; docs-only.
b3c75d3 to
1dda6a5
Compare
Summary
Two classes of rustdoc failures were blocking the Documentation lane:
shipper-types. The outer///doc comment onpub mod storagewas being merged with the module's inner//!docs. Rustdoc then tried to resolve the inner block's[CloudStorageConfig]and[StorageType]links in the parent crate scope, where those items aren't visible. Removing the redundant outer doc lets the module's own//!docs resolve the links correctly.shipper::gitandshipper::authlinked topub(crate)items ([super::bin_override::local_is_git_clean],[credentials::token_from_credentials_file_extended],[crate::ops::git], etc.). Those only resolved because CI runs with--document-private-items, and rustdoc warns under-D warnings. Downgraded them to plain backtick code spans so the prose reads the same but rustdoc is happy either way.Verification
RUSTDOCFLAGS="-Dwarnings" cargo doc --workspace --no-deps --document-private-items— exit 0 (was exit 101 with 9 errors).Test plan
This is PR 3b in the release-hardening sprint — a docs-only companion to PRs 1/2/3.