Conversation
Reviewer's GuideThis PR refactors all bare numeric citations into GitHub Flavored Markdown footnotes, adds a structured “Works cited” section with footnote definitions, and converts the in-document HTML reference table into a pipe-delimited GFM table for consistency and readability. File-Level Changes
|
|
Warning Rate limit exceeded@leynos has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 3 minutes and 36 seconds before requesting another review. ⌛ 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. 📒 Files selected for processing (1)
Summary by CodeRabbit
WalkthroughRevise the Changes
Possibly related PRs
Poem
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey @leynos - I've reviewed your changes - here's some feedback:
- Verify that your documentation host (e.g., GitHub Pages, docs.rs) fully supports GFM-style footnotes and preview the rendered output to catch any broken references.
- Double-check that each [^n] citation correctly matches its footnote definition to prevent orphaned or duplicate references in the works-cited section.
- For future formatting overhauls, consider splitting large refactors into smaller commits or logical chunks to make review and validation safer and more manageable.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- Verify that your documentation host (e.g., GitHub Pages, docs.rs) fully supports GFM-style footnotes and preview the rendered output to catch any broken references.
- Double-check that each [^n] citation correctly matches its footnote definition to prevent orphaned or duplicate references in the works-cited section.
- For future formatting overhauls, consider splitting large refactors into smaller commits or logical chunks to make review and validation safer and more manageable.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🔭 Outside diff range comments (1)
docs/rust-doctest-dry-guide.md (1)
160-164: Use capital “OK” and the ellipsis character.Change
Ok(())→OK(()), and replace<...>with…to meet en-GB spelling and typographical rules.-/// # Ok(()) +/// # OK(())
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
docs/rust-doctest-dry-guide.md(8 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
docs/**/*.md
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- AGENTS.md
**/*.md
Instructions used from:
Sources:
📄 CodeRabbit Inference Engine
- AGENTS.md
⚙️ CodeRabbit Configuration File
🪛 LanguageTool
docs/rust-doctest-dry-guide.md
[uncategorized] ~20-~20: Loose punctuation mark.
Context: ...a developer executes cargo test --doc, rustdoc initiates a multi-stage proce...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~61-~61: Possible missing comma found.
Context: ...te)`). This is not a bug or an oversight but a fundamental aspect of the design, enf...
(AI_HYDRA_LEO_MISSING_COMMA)
[grammar] ~80-~80: Please add a punctuation mark at the end of paragraph.
Context: ...private functions must either be marked as ignore, forgoing the test guarantee,...
(PUNCTUATION_PARAGRAPH_END)
[uncategorized] ~82-~82: Loose punctuation mark.
Context: ...tions must either be marked as ignore, forgoing the test guarantee, or be dupl...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~103-~103: This phrase is redundant. Consider using “inside”.
Context: ...): These document the item they are inside of (e.g., a module or the crate itself). T...
(OUTSIDE_OF)
[grammar] ~123-~123: Please add a punctuation mark at the end of paragraph.
Context: ...tem's purpose. For instance, an example for String::clone() should not just show...
(PUNCTUATION_PARAGRAPH_END)
[misspelling] ~142-~142: This word is normally spelled as one.
Context: ...rongly discouraged. It is considered an anti-pattern because users often copy example code v...
(EN_COMPOUNDS_ANTI_PATTERN)
[style] ~205-~205: Consider using the typographical ellipsis character here instead.
Context: ... error-handling examples, the entire fn main() -> Result<...> {... } and Ok(()) scaffolding ca...
(ELLIPSIS)
[locale-violation] ~205-~205: Lower-case ‘Ok’ is American English. For British English use “OK”.
Context: ...e fn main() -> Result<...> {... } and Ok(()) scaffolding can be hidden, pres...
(OK)
[style] ~215-~215: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...s can sometimes be hidden to de-clutter very simple examples. The existence of features...
(EN_WEAK_ADJECTIVE)
[style] ~221-~221: This word has been used in one of the immediately preceding sentences. Using a synonym could make your text more interesting to read, unless the repetition is intentional.
Context: ...ver, the ideal documentation example is often just a small, illustrative snippet that...
(EN_REPEATEDWORDS_OFTEN)
[style] ~242-~242: The word ‘Caveats’ is a legal term. To make your text as clear as possible to all readers, do not use this foreign term unless it is used with its legal meaning. Possible alternatives are “cautions” or “warnings”.
Context: ... | Primary Use Case & Caveats ...
(CAVEAT)
[misspelling] ~244-~244: This word is normally spelled as one.
Context: ... | Use Case: For pseudo-code, examples known to be broken, or to tem...
(EN_COMPOUNDS_PSEUDO_CODE)
[style] ~244-~244: The word ‘Caveat’ is a legal term. To make your text as clear as possible to all readers, do not use this foreign term unless it is used with its legal meaning. Possible alternatives are “caution” or “warning”.
Context: ...oken, or to temporarily disable a test. Caveat: Provides no guarantee that the code is...
(CAVEAT)
[locale-violation] ~245-~245: Lower-case ‘ok’ is American English. For British English use “OK”.
Context: ...e test passes if the code panics. | ok on panic, failed if it does not panic. ...
(OK)
[locale-violation] ~246-~246: Lower-case ‘ok’ is American English. For British English use “OK”.
Context: ...The test passes if compilation fails. | ok on compilation failure, failed if it co...
(OK)
[style] ~246-~246: The word ‘Caveat’ is a legal term. To make your text as clear as possible to all readers, do not use this foreign term unless it is used with its legal meaning. Possible alternatives are “caution” or “warning”.
Context: ...row checker or type system constraints. Caveat: Highly brittle. A future Rust version ...
(CAVEAT)
[locale-violation] ~247-~247: Lower-case ‘ok’ is American English. For British English use “OK”.
Context: ... execute it. | ok if compilation succeeds. ...
(OK)
[locale-violation] ~248-~248: Lower-case ‘ok’ is American English. For British English use “OK”.
Context: ...ecified Rust edition's rules. | ok on success. ...
(OK)
[uncategorized] ~252-~252: Loose punctuation mark.
Context: ...Detailed Attribute Breakdown - ignore: This is the bluntest instrument in the ...
(UNLIKELY_OPENING_PUNCTUATION)
[misspelling] ~256-~256: This word is normally spelled as one.
Context: ... non-Rust code blocks or illustrative pseudo-code. - should_panic: This attribute inve...
(EN_COMPOUNDS_PSEUDO_CODE)
[uncategorized] ~258-~258: Loose punctuation mark.
Context: ...ustrative pseudo-code. - should_panic: This attribute inverts the normal test ...
(UNLIKELY_OPENING_PUNCTUATION)
[style] ~261-~261: Consider using a more formal/concise alternative here.
Context: ...s successfully or panics for a reason other than the one expected (if a specific panic m...
(OTHER_THAN)
[uncategorized] ~263-~263: Loose punctuation mark.
Context: ...sage is asserted).[^3] - compile_fail: This is a powerful tool for creating ed...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~270-~270: Loose punctuation mark.
Context: ...ch would break the test.[^4] - no_run: This attribute strikes a crucial balanc...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~277-~277: Loose punctuation mark.
Context: ...thout executing it.[^5] - edition20xx: This attribute allows an example to be ...
(UNLIKELY_OPENING_PUNCTUATION)
[formatting] ~303-~303: If the ‘because’ clause is essential to the meaning, do not use a comma before the clause.
Context: ...ed by #[cfg(test)]. This will not work, because rustdoc does not enable the test co...
(COMMA_BEFORE_BECAUSE)
[grammar] ~418-~418: Please add a punctuation mark at the end of paragraph.
Context: ...mpiler.[^15] The compiler only sees the host cfg (e.g., target_os = "windows"),...
(PUNCTUATION_PARAGRAPH_END)
[locale-violation] ~452-~452: Lower-case ‘ok’ is American English. For British English use “OK”.
Context: ... runs, does nothing, and is reported as ok. While simple to write, this can be mi...
(OK)
[style] ~481-~481: Consider using the typographical ellipsis character here instead.
Context: ...ocumentation. This is achieved with the #[doc(cfg(...))] attribute, which requires enabling ...
(ELLIPSIS)
[style] ~508-~508: Since ownership is already implied, this phrasing may be redundant.
Context: ...hree distinct types of tests, each with its own purpose: - Doctests: These are ide...
(PRP_OWN)
[style] ~519-~519: Consider using the typographical ellipsis character here instead.
Context: ...dules within your source files (often mod tests {... }) and are compiled only with `#[cfg...
(ELLIPSIS)
[style] ~565-~565: Consider using the typographical ellipsis character here instead.
Context: ...ub and crates.io, where hidden lines (#...) look like ugly, commented-out code. A...
(ELLIPSIS)
[grammar] ~580-~580: Please add a punctuation mark at the end of paragraph.
Context: ... first write and debug the example as a standard #[test] function in a temporary fi...
(PUNCTUATION_PARAGRAPH_END)
[style] ~605-~605: Consider using the typographical ellipsis character here instead.
Context: ...f fallible functions, always use the fn main() -> Result<...> pattern, hiding the boilerplate. Avoi...
(ELLIPSIS)
[style] ~612-~612: Consider using the typographical ellipsis character here instead.
Context: ...ity* in the final documentation. Use #[cfg(feature = "...")] or other cfg flags inside th...
(ELLIPSIS)
[style] ~620-~620: You have already used ‘right’ in nearby sentences. Consider using an alternative word to let your writing stand out and sound more polished.
Context: ...a square peg into a round hole. Use the right tool for the job. ### Works cited [^1...
(REP_RIGHT)
[typographical] ~624-~624: To join two clauses or introduce examples, consider using an em dash.
Context: ...or the job. ### Works cited [^1]: rust - How can I write documentation tests for ...
(DASH_RULE)
[typographical] ~626-~626: Except for inverted sentences, ‘can I’ requires a question mark at the end of the sentence.
Context: ... accessed on July 15, 2025, https://stackoverflow.com/questions/70111757/how-can-i-write-documentation-tests-for-private-modules [^2]: Rustdoc doctests need fixing - ...
(MD_PRP_QUESTION_MARK)
[typographical] ~628-~628: To join two clauses or introduce examples, consider using an em dash.
Context: ...les> [^2]: Rustdoc doctests need fixing - Swatinem, accessed on July 15, 2025, ...
(DASH_RULE)
[typographical] ~631-~631: To join two clauses or introduce examples, consider using an em dash.
Context: ...fix-rustdoc/> [^3]: Documentation tests - The rustdoc book - Rust Documentation, a...
(DASH_RULE)
[typographical] ~631-~631: To join two clauses or introduce examples, consider using an em dash.
Context: ...: Documentation tests - The rustdoc book - Rust Documentation, accessed on Ju...
(DASH_RULE)
[typographical] ~641-~641: To join two clauses or introduce examples, consider using an em dash.
Context: ...> [^6]: How to organize your Rust tests - LogRocket Blog, accessed on July 15, ...
(DASH_RULE)
[typographical] ~646-~646: To join two clauses or introduce examples, consider using an em dash.
Context: ...rust/> [^8]: Writing Rust Documentation - DEV Community, accessed on July 15, 2025...
(DASH_RULE)
[typographical] ~652-~652: To join two clauses or introduce examples, consider using an em dash.
Context: ...t-is-rustdoc.html> [^10]: Documentation - Rust API Guidelines, accessed on July 15...
(DASH_RULE)
[typographical] ~655-~655: To join two clauses or introduce examples, consider using an em dash.
Context: ...1]: Best practice for doc testing README - help - The Rust Programming Langu...
(DASH_RULE)
[typographical] ~655-~655: To join two clauses or introduce examples, consider using an em dash.
Context: ...t practice for doc testing README - help - The Rust Programming Language For...
(DASH_RULE)
[typographical] ~659-~659: To join two clauses or introduce examples, consider using an em dash.
Context: ...mpile_fail doc test ignored in cfg(test) - help - The Rust Programming Langu...
(DASH_RULE)
[typographical] ~659-~659: To join two clauses or introduce examples, consider using an em dash.
Context: ...ail doc test ignored in cfg(test) - help - The Rust Programming Language For...
(DASH_RULE)
[typographical] ~666-~666: To join two clauses or introduce examples, consider using an em dash.
Context: ...or-doctests/50426> [^14]: quote_doctest - Rust - Docs.rs, access...
(DASH_RULE)
[typographical] ~666-~666: To join two clauses or introduce examples, consider using an em dash.
Context: ...ests/50426> [^14]: quote_doctest - Rust - Docs.rs, accessed on J...
(DASH_RULE)
[typographical] ~669-~669: To join two clauses or introduce examples, consider using an em dash.
Context: ...quote-doctest> [^15]: Advanced features - The rustdoc book - Rust Documentation, a...
(DASH_RULE)
[typographical] ~669-~669: To join two clauses or introduce examples, consider using an em dash.
Context: ...5]: Advanced features - The rustdoc book - Rust Documentation, accessed on J...
(DASH_RULE)
[typographical] ~672-~672: To join two clauses or introduce examples, consider using an em dash.
Context: ...doc/advanced-features.html> [^16]: rust - How can I conditionally execute a module...
(DASH_RULE)
[typographical] ~674-~674: Except for inverted sentences, ‘can I’ requires a question mark at the end of the sentence.
Context: ... accessed on July 15, 2025, https://stackoverflow.com/questions/50312190/how-can-i-conditionally-execute-a-module-level-doctest-based-on-a-feature-flag have doctests?, accessed on Ju...
(MD_PRP_QUESTION_MARK)
[uncategorized] ~679-~679: Loose punctuation mark.
Context: ...[^18]: How do you write your doc tests? : r/rust - Reddit, accessed on July 15, ...
(UNLIKELY_OPENING_PUNCTUATION)
[typographical] ~679-~679: To join two clauses or introduce examples, consider using an em dash.
Context: ...ow do you write your doc tests? : r/rust - Reddit, accessed on July 15, 2025...
(DASH_RULE)
leynos
deleted the
codex/change-numbered-footnotes-to-enumerated-footnotes
branch
1 participant
Summary
Testing
make fmtmake lintmake testhttps://chatgpt.com/codex/tasks/task_e_687ad8ebcf408322aad6793238a1fcab
Summary by Sourcery
Convert inline numeric citations in the Rust doctest guide to GitHub Flavored Markdown footnotes and append a works cited section listing the sources.
Enhancements:
Documentation: