Skip to content

Make odoc references in documentation comments navigable - #2139

Open
N1ark wants to merge 5 commits into
ocaml:masterfrom
N1ark:resolve-doc-links
Open

Make odoc references in documentation comments navigable#2139
N1ark wants to merge 5 commits into
ocaml:masterfrom
N1ark:resolve-doc-links

Conversation

@N1ark

@N1ark N1ark commented Aug 11, 2026

Copy link
Copy Markdown

Fixes #436.

Implement textDocument/documentLink and documentLink/resolve, which report the links an odoc comment contains, so editors underline them and cmd-click opens them:

type t = Foo

(** Know if a value of type {!t} is {!Foo}.
    See {{:https://ocaml.org} the site}.
    @see <https://ocaml.org/manual> the manual *)
let is_foo Foo = true

In the above example, t, Foo, https://ocaml.org and https://ocaml.org/manual are all clickable! Same if you hover the function and click in the markdown docs. Cross-references are resolved lazily. Cross-module and stdlib references work wherever go-to-definition does, i.e. once the project is built; {!Stdlib.List.map} opens the compiler's list.ml.

This is best reviewed commit by commit; all increments build and all tests pass at each step.

The PR is bigger than I initially planned. If it's easier for you I'm happy to split it into ~3 PRs, following the structure given by the commits here!

Implementation Details

The system for handling odoc references is in Odoc_reference. From there, we call Merlin_analysis.Locate.from_string rather than Query_protocol.Locate, as we need to select exactly in what environment we're looking for the reference. The environment is obtained from Typedtree, which is not ideal, but e.g. Locate also uses it, so I felt like it was probably ok, for such a light usage.

All functions in Doc_to_md have a new ?resolve parameter, to resolve references to hyperlinks. The change is a bit churny, sorry about that. If you have a better idea to avoid it let me know :)

Also had to tweak Uri.to_string, it used to percent-encode sub-delimiters in queries and fragments, so a URL like https://x.dev/s?q=a&n=1 was escaped as https://x.dev/s?q%3Da%26n%3D1, which is wrong.

Note

I acknowledge this PR was mostly written by an LLM. I took care of directing it, and reviewing the changes along with cleaning up parts of the code and comment.

@N1ark
N1ark force-pushed the resolve-doc-links branch from 7053dc0 to 3554018 Compare August 11, 2026 22:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature request] Display/honor cross references in documentation

1 participant