docs: Add rustdocs link policy section
What the developer wrote
Authored by Tobin C. Harding
docs: Add rustdocs link policy section
With comment
https://github.com/rust-bitcoin/rust-bitcoin/issues/4859#issuecomment-3190333850
we decided to favour links at the bottom of a docs section instead of
inline.
Document this policy.
What changed, and why it matters
This commit only adds a documentation policy guideline about how to format hyperlink references in Rust source-code comments. It does not change any executable code, cryptographic logic, network handling, or APIs.
No security action needed; this is a documentation-only policy change.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff appends a new ‘Links’ subsection to docs/policy.md describing the project’s preference for placing Markdown link definitions at the bottom of a docs section rather than using inline links. No Rust source files, build scripts, tests, or dependencies were modified.
Changed components
docs/policy.mdInspect captured patch +12 / −0
diff --git a/docs/policy.md b/docs/policy.md
index f38a50a9..85dff126 100644
--- a/docs/policy.md
+++ b/docs/policy.md
@@ -226,6 +226,18 @@ panics that could theoretically occur because of bugs in our code must not be do
Example code within the rustdocs should compile and lint with `just lint` without any errors or
warnings.
+### Links
+
+We favour links at the bottom of the docs section:
+
+```rust
+ /// it is a real Taproot script spend (and not some other kind of output contrived
+ /// to have a Taproot-shaped witness). See [BIP-0341] in particular footnote 7, for
+ /// more information.
+ ///
+ /// [BIP-0341]: <https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki>
+```
+
## Derives
We try to use standard set of derives if it makes sense:
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.