@@ -23,31 +23,49 @@ comments that reference the corresponding OCaml code. This helps developers:
2323
2424## Comment format
2525
26- OCaml references are added as doc comments directly above the Rust type or
27- function:
26+ OCaml references are added as single-line doc comments directly above the Rust
27+ type or function, using a clickable hyperlink format :
2828
2929``` rust
30- /// OCaml reference: src/lib/mina_base/transaction_status.ml L:9-113
31- /// Commit: 55582d249cdb225f722dbbb3b1420ce7570d501f
32- /// Last verified: 2025-10-08
30+ /// OCaml: <https://github.com/MinaProtocol/mina/blob/5da42ccd72e791f164d4d200cf1ce300262873b3/src/lib/mina_base/transaction_status.ml#L9-L51>
3331pub enum TransactionFailure {
3432 // ...
3533}
3634```
3735
3836### Format specification
3937
40- - ** Line 1** : ` /// OCaml reference: <path> L:<start>-<end> `
41- - ` <path> ` : Path to the OCaml file relative to the Mina repository root
42- - ` L:<start>-<end> ` : Line range in the OCaml file (optional but recommended)
43- - ** Line 2** : ` /// Commit: <commit-hash> `
44- - Full commit hash from the Mina repository
45- - ** Line 3** : ` /// Last verified: <YYYY-MM-DD> `
46- - Date when the reference was last verified to be accurate
38+ The format is: ` /// OCaml: <URL> `
39+
40+ Where the URL follows this structure:
41+
42+ ```
43+ https://github.com/MinaProtocol/mina/blob/<commit-hash>/<path>#L<start>-L<end>
44+ ```
45+
46+ - ` <commit-hash> ` : Full commit hash from the Mina repository (40 characters)
47+ - ` <path> ` : Path to the OCaml file relative to the Mina repository root
48+ - ` #L<start>-L<end> ` : Line range in the OCaml file (optional but recommended)
49+
50+ ** Benefits of this format** :
51+
52+ - Single line is easier to read and maintain
53+ - Clickable in IDEs and GitHub
54+ - Commit hash embedded in URL preserves historical tracking
55+ - Line range visible directly in URL fragment
56+ - Works in markdown viewers and documentation
4757
4858## Validation script
4959
50- The ` .github/scripts/check-ocaml-refs.sh ` script validates all OCaml references:
60+ The ` .github/scripts/check-ocaml-refs.sh ` script validates all OCaml references.
61+
62+ ::: note
63+
64+ The validation script is being updated to support the new hyperlink format. In
65+ the meantime, newly added references using the hyperlink format will not be
66+ automatically validated by CI.
67+
68+ :::
5169
5270``` bash
5371# Validate against compatible branch (default)
@@ -91,16 +109,14 @@ The workflow can also be triggered manually via the Actions tab.
91109When implementing new features from the OCaml codebase:
92110
931111 . Add the OCaml reference comment above your Rust type/function
94- 2 . Use the current commit hash from the Mina repository
95- 3 . Set the verification date to today
96- 4 . Include line ranges to make it easy to find the exact code
112+ 2 . Use the current commit hash from the Mina repository (full 40-character hash)
113+ 3 . Include line ranges to make it easy to find the exact code
114+ 4 . Use angle brackets around the URL for automatic linking
97115
98116Example:
99117
100118``` rust
101- /// OCaml reference: src/lib/mina_base/fee_transfer.ml L:19-45
102- /// Commit: 55582d249cdb225f722dbbb3b1420ce7570d501f
103- /// Last verified: 2025-10-08
119+ /// OCaml: <https://github.com/MinaProtocol/mina/blob/5da42ccd72e791f164d4d200cf1ce300262873b3/src/lib/mina_base/fee_transfer.ml#L19-L45>
104120#[derive(Debug , Clone , PartialEq )]
105121pub struct SingleFeeTransfer {
106122 pub receiver_pk : CompressedPubKey ,
0 commit comments