style(bindings): standardize doc links to monospaced format#5791
Open
style(bindings): standardize doc links to monospaced format#5791
Conversation
Replace [s2n_xxx] with [`s2n_xxx`] in all Rust doc comments to render links in monospaced font, matching tokio and rustdoc conventions. Also updates grep_simple_mistakes.sh to recognize the new format. Fixes aws#5095
jmayclin
approved these changes
Mar 20, 2026
Contributor
|
Also, I personally consider |
CarolYeh910
reviewed
Mar 20, 2026
| CALLS=`grep -ro "$api(" $BINDINGS | wc -l` | ||
| if [ "$CALLS" == 0 ]; then continue; fi | ||
| DOCS=`grep -ro "///.* \[$api\]" $BINDINGS | wc -l` | ||
| DOCS=`grep -ro "///.* \[\`\?$api\`\?\]" $BINDINGS | wc -l` |
Contributor
There was a problem hiding this comment.
If I understand correctly, this regex would match either [`s2n_api`] or [s2n_api]? If we're enforcing the monospaced format, we should probably remove \?.
| printf "\e[1;34mRust bindings are missing documentation links:\e[0m " | ||
| printf "Where possible, the Rust bindings should link to existing documentation. " | ||
| printf "Links can be written like \"[s2n_connection_new]\".\n" | ||
| printf "Links can be written like \"[\\\`s2n_connection_new\\\`]\".\n" |
Contributor
There was a problem hiding this comment.
We don't need an explicit \ in the printf output, right? Maybe just do
\"[\`s2n_connection_new\`]\"
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
Summary
Standardizes all Rust doc comment links from
[s2n_xxx]to[`s2n_xxx`]across 14 files in the Rust bindings, and updatesgrep_simple_mistakes.shto match.Why this matters
Doc links were inconsistently formatted (#5095). The monospaced backtick format (
[`s2n_xxx`]) matches the convention used by tokio, the rustdoc book, and most Rust ecosystem crates.Changes
.rsfiles inbindings/rust/extended/s2n-tls/src/codebuild/bin/grep_simple_mistakes.shto recognize the new format and print updated guidanceOnly doc comment lines (
///) were modified. No code changes.Testing
Verified with
git diffthat no non-doc-comment lines were touched. The[s2n_security_policy_selection]array type inlib.rswas correctly left untouched.Fixes #5095
This contribution was developed with AI assistance (Claude Code).