Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: Clean up doc comments #14823

Merged
merged 4 commits into from
Nov 15, 2024
Merged

docs: Clean up doc comments #14823

merged 4 commits into from
Nov 15, 2024

Conversation

epage
Copy link
Contributor

@epage epage commented Nov 15, 2024

What does this PR try to resolve?

I'm experimenting with API changes in Cargo and wanted to make it easier to find doc comments that need updating. I didn't see a lint to help with this but I did go ahead and apply the result of other documentation lints.

How should we test and review this PR?

I've not turned these lints on more generally

  • clippy::doc_markdown has some false positives we'd need to record in our config (SemVer and SQLite)
  • clippy::too_long_first_doc_paragraph pointed out a doc comment that, at a quick glance, I didn't see what summary to provide

I also didn't wanted to get this in without making a policy decision of what lints are enabled.

Additional information

@rustbot
Copy link
Collaborator

rustbot commented Nov 15, 2024

r? @ehuss

rustbot has assigned @ehuss.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

@rustbot rustbot added A-build-execution Area: anything dealing with executing the compiler A-build-scripts Area: build.rs scripts A-cache-messages Area: caching of compiler messages A-cfg-expr Area: Platform cfg expressions A-cli Area: Command-line interface, option parsing, etc. A-cli-help Area: built-in command-line help A-configuration Area: cargo config files and env vars A-credential-provider Area: credential provider for storing and retreiving credentials A-dependency-resolution Area: dependency resolution and the resolver A-environment-variables Area: environment variables A-features2 Area: issues specifically related to the v2 feature resolver A-git Area: anything dealing with git A-home Area: the `home` crate A-interacts-with-crates.io Area: interaction with registries A-layout Area: target output directory layout, naming, and organization A-manifest Area: Cargo.toml issues A-profiles Area: profiles A-rebuild-detection Area: rebuild detection and fingerprinting A-registries Area: registries A-registry-authentication Area: registry authentication and authorization (authn authz) A-semver Area: semver specifications, version matching, etc. A-testing-cargo-itself Area: cargo's tests A-timings Area: timings A-unstable Area: nightly unstable support A-workspaces Area: workspaces Command-add Command-fix Command-new labels Nov 15, 2024
@rustbot rustbot added Command-tree Command-update S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 15, 2024
@ehuss
Copy link
Contributor

ehuss commented Nov 15, 2024

Thanks! Can you bump the version of cargo-credential to fix the version-bump job (and any other packages that need bumping)?

epage added 4 commits November 15, 2024 09:33
@epage
chore: Bump cargo-credential
179c516
@epage
docs: Turn relative links to intra-doc links
0b28167
@epage
docs: Surround identifiers in backticks
878caf7 
This was mostly done by clippy via `clippy::doc_markdown`.
I then reviewed it to fix words that shouldn't have it or where `--fix`
put the backtick in the wrong location.
@epage
docs: Focus the summary for API items
e306556 
This was aided by `clippy::too_long_first_doc_paragraph`
@ehuss
Copy link
Contributor

ehuss commented Nov 15, 2024

Looks like Cargo.lock also needs updating.

@ehuss
Copy link
Contributor

ehuss commented Nov 15, 2024

Thanks!

@bors r+

@bors
Copy link
Contributor

bors commented Nov 15, 2024

@ehuss: 🔑 Insufficient privileges: Not in reviewers

ehuss
ehuss approved these changes Nov 15, 2024
View reviewed changes
Copy link
Contributor

@ehuss ehuss left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oops, wrong bot.

@ehuss ehuss added this pull request to the merge queue Nov 15, 2024
Merged via the queue into rust-lang:master with commit a8f7db2 Nov 15, 2024
22 checks passed
@epage epage deleted the rustdoc branch November 15, 2024 18:34
@weihanglo weihanglo mentioned this pull request Nov 16, 2024
Merged
bors added a commit to rust-lang-ci/rust that referenced this pull request Nov 16, 2024
@bors
Auto merge of rust-lang#133094 - weihanglo:update-cargo, r=weihanglo
b74a83e 
Update cargo

15 commits in 4a2d8dc636445b276288543882e076f254b3ae95..69e595908e2c420e7f0d1be34e6c5b984c8cfb84
2024-11-09 19:10:33 +0000 to 2024-11-16 01:26:11 +0000
- refactor(fingerprint): Track the intent for each use of `UnitHash` (rust-lang/cargo#14826)
- fix(toml): Update frontmatter parser for RFC 3503 (rust-lang/cargo#14792)
- docs(unstable): Move -Zwarnings from stable to unstable section (rust-lang/cargo#14827)
- Simplify English used in guide (rust-lang/cargo#14825)
- feat(resolver): Stabilize resolver v3 (rust-lang/cargo#14754)
- docs: Clean up doc comments (rust-lang/cargo#14823)
- fix(remove): On error, suggest other dependencies  (rust-lang/cargo#14818)
- Always include Cargo.lock in published crates (rust-lang/cargo#14815)
- fix(build-rs)!: Updates from an audit (rust-lang/cargo#14817)
- feat(rustdoc): diplay env vars in extra verbose mode  (rust-lang/cargo#14812)
- Migrate build-rs to the Cargo repo (rust-lang/cargo#14786)
- chore(ci): Check for clippy `correctness` (rust-lang/cargo#14796)
- git: do not validate submodules of fresh checkouts (rust-lang/cargo#14605)
- refactor: clone-on-write when needed for InternedString (rust-lang/cargo#14808)
- fix(docs): typo in cargo-fmt.md (rust-lang/cargo#14805)
bors added a commit to rust-lang-ci/rust that referenced this pull request Nov 16, 2024
@bors
Auto merge of rust-lang#133094 - weihanglo:update-cargo, r=weihanglo
3e4849e 
Update cargo

15 commits in 4a2d8dc636445b276288543882e076f254b3ae95..69e595908e2c420e7f0d1be34e6c5b984c8cfb84
2024-11-09 19:10:33 +0000 to 2024-11-16 01:26:11 +0000
- refactor(fingerprint): Track the intent for each use of `UnitHash` (rust-lang/cargo#14826)
- fix(toml): Update frontmatter parser for RFC 3503 (rust-lang/cargo#14792)
- docs(unstable): Move -Zwarnings from stable to unstable section (rust-lang/cargo#14827)
- Simplify English used in guide (rust-lang/cargo#14825)
- feat(resolver): Stabilize resolver v3 (rust-lang/cargo#14754)
- docs: Clean up doc comments (rust-lang/cargo#14823)
- fix(remove): On error, suggest other dependencies  (rust-lang/cargo#14818)
- Always include Cargo.lock in published crates (rust-lang/cargo#14815)
- fix(build-rs)!: Updates from an audit (rust-lang/cargo#14817)
- feat(rustdoc): diplay env vars in extra verbose mode  (rust-lang/cargo#14812)
- Migrate build-rs to the Cargo repo (rust-lang/cargo#14786)
- chore(ci): Check for clippy `correctness` (rust-lang/cargo#14796)
- git: do not validate submodules of fresh checkouts (rust-lang/cargo#14605)
- refactor: clone-on-write when needed for InternedString (rust-lang/cargo#14808)
- fix(docs): typo in cargo-fmt.md (rust-lang/cargo#14805)
bors added a commit to rust-lang-ci/rust that referenced this pull request Nov 17, 2024
@bors
Auto merge of rust-lang#133094 - weihanglo:update-cargo, r=weihanglo
5afd5ad 
Update cargo

15 commits in 4a2d8dc636445b276288543882e076f254b3ae95..69e595908e2c420e7f0d1be34e6c5b984c8cfb84
2024-11-09 19:10:33 +0000 to 2024-11-16 01:26:11 +0000
- refactor(fingerprint): Track the intent for each use of `UnitHash` (rust-lang/cargo#14826)
- fix(toml): Update frontmatter parser for RFC 3503 (rust-lang/cargo#14792)
- docs(unstable): Move -Zwarnings from stable to unstable section (rust-lang/cargo#14827)
- Simplify English used in guide (rust-lang/cargo#14825)
- feat(resolver): Stabilize resolver v3 (rust-lang/cargo#14754)
- docs: Clean up doc comments (rust-lang/cargo#14823)
- fix(remove): On error, suggest other dependencies  (rust-lang/cargo#14818)
- Always include Cargo.lock in published crates (rust-lang/cargo#14815)
- fix(build-rs)!: Updates from an audit (rust-lang/cargo#14817)
- feat(rustdoc): diplay env vars in extra verbose mode  (rust-lang/cargo#14812)
- Migrate build-rs to the Cargo repo (rust-lang/cargo#14786)
- chore(ci): Check for clippy `correctness` (rust-lang/cargo#14796)
- git: do not validate submodules of fresh checkouts (rust-lang/cargo#14605)
- refactor: clone-on-write when needed for InternedString (rust-lang/cargo#14808)
- fix(docs): typo in cargo-fmt.md (rust-lang/cargo#14805)
@weihanglo weihanglo added this to the 1.84.0 milestone Nov 28, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ehuss ehuss ehuss approved these changes

Assignees

@ehuss ehuss

Labels
A-build-execution Area: anything dealing with executing the compiler A-build-scripts Area: build.rs scripts A-cache-messages Area: caching of compiler messages A-cfg-expr Area: Platform cfg expressions A-cli Area: Command-line interface, option parsing, etc. A-cli-help Area: built-in command-line help A-configuration Area: cargo config files and env vars A-credential-provider Area: credential provider for storing and retreiving credentials A-dependency-resolution Area: dependency resolution and the resolver A-environment-variables Area: environment variables A-features2 Area: issues specifically related to the v2 feature resolver A-git Area: anything dealing with git A-home Area: the `home` crate A-interacts-with-crates.io Area: interaction with registries A-layout Area: target output directory layout, naming, and organization A-manifest Area: Cargo.toml issues A-profiles Area: profiles A-rebuild-detection Area: rebuild detection and fingerprinting A-registries Area: registries A-registry-authentication Area: registry authentication and authorization (authn authz) A-semver Area: semver specifications, version matching, etc. A-testing-cargo-itself Area: cargo's tests A-timings Area: timings A-unstable Area: nightly unstable support A-workspaces Area: workspaces Command-add Command-fix Command-new Command-tree Command-update S-waiting-on-review Status: Awaiting review from the assignee but also interested parties.
Projects
None yet
Milestone
1.84.0
Development

Successfully merging this pull request may close these issues.
5 participants
@epage @rustbot @ehuss @bors @weihanglo