Update the rustdoc example to match best practice #1804
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This change updates the meta/doc example to match the best practices outlined in RFC 1574 (already referenced by the doc). Specifically, it removes the "Arguments" section from the `Person` doc example. I've also added a mention of `cargo doc --open` as it's pretty useful and people may not think to see if it exists.
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @marioidival (or someone else) soon. |
|
For some flavour as to why I want this change - I attempt to advise someone that Rust docs generally avoid enumerating all the arguments like javadoc and they pointed me to this example. |
|
@Skepfyr thanks! |
GuillaumeGomez
added a commit
to GuillaumeGomez/rust
that referenced
this pull request
Jan 30, 2024
Update books ## rust-lang/edition-guide 1 commits in bbffb074e16bef89772818b400b6c76a65eac126..baafacc6d8701269dab1e1e333f3547fb54b5a59 2024-01-18 18:44:06 UTC to 2024-01-18 18:44:06 UTC - Update c-string literal stabilization release number. (rust-lang/edition-guide#289) ## rust-embedded/book 1 commits in 3f9df2b9885c6741365da2e12ed6662cd0e827d6..2e95fc2fd31d669947e993aa07ef10dc9828bee7 2024-01-29 07:19:07 UTC to 2024-01-29 07:19:07 UTC - Mention generics in "optimizing dependencies" (rust-embedded/book#366) ## rust-lang/reference 3 commits in 8c77e8be9da1a9c70545556218d563c8d061f1fd..a0b119535e7740f68494c4f0582f7ad008b00ccd 2024-01-27 19:22:06 UTC to 2024-01-27 16:43:49 UTC - Update C-String literals to reject NUL (rust-lang/reference#1450) - pure asm blocks must terminate (rust-lang/reference#1442) - String literal expressions (rust-lang/reference#1452) ## rust-lang/rust-by-example 4 commits in ddf5cb0e6ee54ba2dd84c8ca3e1314120014e20d..179256a445d6144f5f371fdefb993f48f33978b0 2024-01-22 12:21:42 UTC to 2024-01-20 23:10:42 UTC - Updated first sentence of "parsing a string" in string.md (rust-lang/rust-by-example#1805) - Update the rustdoc example to match best practice (rust-lang/rust-by-example#1804) - Add reference to crates.io error handling crates (rust-lang/rust-by-example#1803) - fix(str.md): avoid misunderstanding that there were only two string types (rust-lang/rust-by-example#1802) ## rust-lang/rustc-dev-guide 15 commits in 4af29d1a7f64f88a36539662c6a84fe1fbe6cde1..ec287e332777627185be4798ad22599ffe7b84aa 2024-01-28 22:45:18 UTC to 2024-01-15 17:44:49 UTC - Upgrade actions to use Node.js v20 (rust-lang/rustc-dev-guide#1863) - Fix some links (rust-lang/rustc-dev-guide#1865) - Add link in salsa (rust-lang/rustc-dev-guide#1866) - Clarify what rt.rs is. (rust-lang/rustc-dev-guide#1876) - update link to rustc dependencies (rust-lang/rustc-dev-guide#1869) - Followup to rust-lang#1862 (rust-lang/rustc-dev-guide#1864) - Clarify debugging graph dependency (rust-lang/rustc-dev-guide#1862) - Get diagnostics directly in `rustc-driver-getting-diagnostics` example (rust-lang/rustc-dev-guide#1857) - Update examples (rust-lang/rustc-dev-guide#1856) - Add a perf. bot command and a link to its help page (rust-lang/rustc-dev-guide#1855) - Add some explanations for frequently used rustbot commands (rust-lang/rustc-dev-guide#1849) - update some of the diagnostic translations info (rust-lang/rustc-dev-guide#1711) - Document unsafety checking (rust-lang/rustc-dev-guide#1847) - Remove outdated references to `-Z dump-mir-spanview` (rust-lang/rustc-dev-guide#1853) - update old bootstrap docs (rust-lang/rustc-dev-guide#1852)
rust-timer
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Jan 30, 2024
Rollup merge of rust-lang#120467 - rustbot:docs-update, r=ehuss Update books ## rust-lang/edition-guide 1 commits in bbffb074e16bef89772818b400b6c76a65eac126..baafacc6d8701269dab1e1e333f3547fb54b5a59 2024-01-18 18:44:06 UTC to 2024-01-18 18:44:06 UTC - Update c-string literal stabilization release number. (rust-lang/edition-guide#289) ## rust-embedded/book 1 commits in 3f9df2b9885c6741365da2e12ed6662cd0e827d6..2e95fc2fd31d669947e993aa07ef10dc9828bee7 2024-01-29 07:19:07 UTC to 2024-01-29 07:19:07 UTC - Mention generics in "optimizing dependencies" (rust-embedded/book#366) ## rust-lang/reference 3 commits in 8c77e8be9da1a9c70545556218d563c8d061f1fd..a0b119535e7740f68494c4f0582f7ad008b00ccd 2024-01-27 19:22:06 UTC to 2024-01-27 16:43:49 UTC - Update C-String literals to reject NUL (rust-lang/reference#1450) - pure asm blocks must terminate (rust-lang/reference#1442) - String literal expressions (rust-lang/reference#1452) ## rust-lang/rust-by-example 4 commits in ddf5cb0e6ee54ba2dd84c8ca3e1314120014e20d..179256a445d6144f5f371fdefb993f48f33978b0 2024-01-22 12:21:42 UTC to 2024-01-20 23:10:42 UTC - Updated first sentence of "parsing a string" in string.md (rust-lang/rust-by-example#1805) - Update the rustdoc example to match best practice (rust-lang/rust-by-example#1804) - Add reference to crates.io error handling crates (rust-lang/rust-by-example#1803) - fix(str.md): avoid misunderstanding that there were only two string types (rust-lang/rust-by-example#1802) ## rust-lang/rustc-dev-guide 15 commits in 4af29d1a7f64f88a36539662c6a84fe1fbe6cde1..ec287e332777627185be4798ad22599ffe7b84aa 2024-01-28 22:45:18 UTC to 2024-01-15 17:44:49 UTC - Upgrade actions to use Node.js v20 (rust-lang/rustc-dev-guide#1863) - Fix some links (rust-lang/rustc-dev-guide#1865) - Add link in salsa (rust-lang/rustc-dev-guide#1866) - Clarify what rt.rs is. (rust-lang/rustc-dev-guide#1876) - update link to rustc dependencies (rust-lang/rustc-dev-guide#1869) - Followup to rust-lang#1862 (rust-lang/rustc-dev-guide#1864) - Clarify debugging graph dependency (rust-lang/rustc-dev-guide#1862) - Get diagnostics directly in `rustc-driver-getting-diagnostics` example (rust-lang/rustc-dev-guide#1857) - Update examples (rust-lang/rustc-dev-guide#1856) - Add a perf. bot command and a link to its help page (rust-lang/rustc-dev-guide#1855) - Add some explanations for frequently used rustbot commands (rust-lang/rustc-dev-guide#1849) - update some of the diagnostic translations info (rust-lang/rustc-dev-guide#1711) - Document unsafety checking (rust-lang/rustc-dev-guide#1847) - Remove outdated references to `-Z dump-mir-spanview` (rust-lang/rustc-dev-guide#1853) - update old bootstrap docs (rust-lang/rustc-dev-guide#1852)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
#1457 was closed with prejudice ;) so I've made a PR instead!
This change updates the meta/doc example to match the best practices outlined in RFC 1574 (already referenced by the doc). Specifically, it removes the "Arguments" section from the
Persondoc example.I've also added a mention of
cargo doc --openas it's pretty useful and people may not think to see if it exists.I'm also suspicious about all the mentions of invoking
rustdocdirectly as I suspect ~everyone usescargo docbut I haven't touched them in this change.