Summary

Following a team retro, we need to migrate all OCaml reference comments to use
single-line hyperlinks for better trackability and simpler format.

Current state

We have two different formats for OCaml references in the codebase:

1. Multi-line format (documented/CI-tracked)

/// OCaml reference: src/lib/mina_base/transaction_status.ml L:9-51
/// Commit: 5da42ccd72e791f164d4d200cf1ce300262873b3
/// Last verified: 2025-10-08

Found in:

• ledger/src/scan_state/transaction_logic/mod.rs (~20+ references)
• ledger/src/scan_state/transaction_logic/for_tests.rs
• ledger/src/scan_state/transaction_logic/signed_command.rs
• ledger/src/account/account.rs

2. Single-line hyperlink format (not tracked by CI)

// <https://github.com/MinaProtocol/mina/blob/d800da86a764d8d37ffb8964dd8d54d9f522b358/src/lib/mina_block/validation.ml#L369>

Or with markdown link syntax:

/// Location: [src/lib/mina_block/block.ml:8:4](https://github.com/MinaProtocol/mina/blob/1551e2faaa/src/lib/mina_block/block.ml#L8)

Found in:

• core/src/block/prevalidate.rs
• core/src/consensus.rs
• core/src/constants.rs
• mina-p2p-messages/src/string.rs
• node/src/transition_frontier/sync/transition_frontier_sync_reducer.rs
• mina-p2p-messages/src/v2/generated.rs (auto-generated, many entries)

Proposed new format

Standardize on a single-line hyperlink format:

/// OCaml: <https://github.com/MinaProtocol/mina/blob/COMMIT_HASH/path/to/file.ml#L9-L51>

Benefits:

• Single line is easier to read and maintain
• Clickable in IDEs and GitHub
• Commit hash embedded in URL preserves historical tracking
• Line range visible in URL fragment

Tasks

Phase 1: Update existing multi-line format to hyperlinks

• Convert all multi-line /// OCaml reference: comments to hyperlink format
• Files to update:
  • ledger/src/scan_state/transaction_logic/mod.rs
  • ledger/src/scan_state/transaction_logic/for_tests.rs
  • ledger/src/scan_state/transaction_logic/signed_command.rs
  • ledger/src/account/account.rs

Phase 2: Standardize existing hyperlinks

• Audit and standardize existing hyperlink references to use consistent format
• Files to review:
  • core/src/block/prevalidate.rs
  • core/src/consensus.rs
  • core/src/constants.rs
  • mina-p2p-messages/src/string.rs
  • node/src/transition_frontier/sync/transition_frontier_sync_reducer.rs
• Decide how to handle mina-p2p-messages/src/v2/generated.rs (auto-generated)

Phase 3: Update documentation

• Update website/docs/developers/ocaml-reference-tracking.md:
  • Document new hyperlink format
  • Update examples
  • Remove multi-line format documentation
• Update CLAUDE.md if OCaml reference format is mentioned

Phase 4: Update CI

• Update .github/scripts/check-ocaml-refs.sh:
  • Parse hyperlink format instead of multi-line format
  • Extract commit hash and path from URL
  • Validate file existence and line ranges
  • Support auto-update by replacing commit hash in URLs
• Update .github/workflows/check-ocaml-refs.yaml if needed
• Test CI locally with gh act

Implementation notes

1. The hyperlink format should use angle brackets for automatic linking:
   <https://...> not just https://...

2. Consider using a doc comment prefix like /// OCaml: to make references
   searchable

3. For auto-generated files like generated.rs, coordinate with the code
   generator tool

References

• Current documentation: https://o1-labs.github.io/mina-rust/docs/developers/ocaml-reference-tracking
• CI workflow: .github/workflows/check-ocaml-refs.yaml
• Validation script: .github/scripts/check-ocaml-refs.sh