Skip to content

Commit 7a552c0

Browse files
Copilotdannywillems
andcommitted
Phase 3: Update documentation for new hyperlink format
Updated documentation to reflect the new single-line hyperlink format: - website/docs/developers/ocaml-reference-tracking.md: Complete rewrite of format specification and examples - CLAUDE.md: Updated example to use hyperlink format The new format is simpler and more maintainable: /// OCaml: <https://github.com/MinaProtocol/mina/blob/COMMIT/path#L1-L10> Co-authored-by: dannywillems <6018454+dannywillems@users.noreply.github.com>
1 parent f3c8f0d commit 7a552c0

File tree

2 files changed

+36
-22
lines changed

2 files changed

+36
-22
lines changed

CLAUDE.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -170,9 +170,7 @@ to track correspondence and detect when updates are needed.
170170
**Comment format:**
171171

172172
```rust
173-
/// OCaml reference: src/lib/mina_base/transaction_status.ml L:9-113
174-
/// Commit: 55582d249cdb225f722dbbb3b1420ce7570d501f
175-
/// Last verified: 2025-10-08
173+
/// OCaml: <https://github.com/MinaProtocol/mina/blob/5da42ccd72e791f164d4d200cf1ce300262873b3/src/lib/mina_base/transaction_status.ml#L9-L51>
176174
pub enum TransactionFailure {
177175
// ...
178176
}

website/docs/developers/ocaml-reference-tracking.md

Lines changed: 35 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -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>
3331
pub 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.
91109
When implementing new features from the OCaml codebase:
92110

93111
1. 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

98116
Example:
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)]
105121
pub struct SingleFeeTransfer {
106122
pub receiver_pk: CompressedPubKey,

0 commit comments

Comments
 (0)