Documentation fixes: cross-refs, internal links #928
Conversation
|
Thanks for the many fixes. I have a significant question about the essence of the MR itself. I've attached it to a diff chunk but it's really a general question. I can do a more thorough review once it is sorted. |
| @@ -1916,13 +1911,13 @@ val wakeup_paused : unit -> unit | |||
|
|
|||
| val paused_count : unit -> int | |||
| (** Returns the number of promises that would be fulfilled by calling | |||
| {!Lwt.wakeup_paused} right now. | |||
| [Lwt.wakeup_paused] right now. | |||
There was a problem hiding this comment.
Interesting, the target of the reference as well as the reference itself are removed from the documentation with a stop comment but Odoc still tries to resolve the reference and fails. ocaml/odoc#818
src/core/lwt.mli
Outdated
| @@ -54,24 +54,23 @@ let () = | |||
|
|
|||
| This is all explained in the next sections: | |||
|
|
|||
| - {{: #3_Quickstart} Quick start} links these concepts to actual functions | |||
| - {!section-3_Quickstart} links these concepts to actual functions | |||
There was a problem hiding this comment.
All the section-, type: and Lwt. prefixes are not necessary, the references will resolve as long as there's no ambiguity.
There was a problem hiding this comment.
I've removed the unnecessary prefixes, but I'm keeping the module paths: it'd be too long to change at this point.
This PR changes all external hyperlinks to the standard API to odoc cross-references. That way, the offline Lwt doc API will correctly refer to the offline OCaml documentation. The PR also adds more cross-references to the
Unixlibrary, fixes the internal references to never directly use an html anchor, and adds misc. documentation fixes.All of this is aimed at a better odoc/odig integration.
My final goal is also to convert the manual to mld, to have it installable with the opam package and browsable with odig and odoc, but that'll come in a follow-up PR.