References in module preambles aren't working as expected

[jonludlam]

For example, use odig and look at the Astring documentation - the first link is broken {{!strf}one value}

[dbuenzli]

I'll take the opportunity to mention #332 and #42.

In general the resolution strategy for {!id} for needs to be clarified an properly documented, since it differs from the OCaml language.

AFAIR odoc's one always differed from ocamldoc's one. With the years I gradually fixed my links to match odoc's notion but it can become slightly verbose since there are cases where you need to qualify more (of course now I can't find an example).

OTOH I vaguely remember discussing that with @trefis which considered ocamldoc's to be too ambiguous and/or broken.

[dbuenzli]

I just fell on the case that always bothered me with odoc. Basically the problem is that {!id} is oblivious of opens.

Suppose I have:

module Ns : sig
  module A : sig 
  end
end

Now in the following module {!A} does not get resolved:

module B sig 
   open Ns

   (** see {!A} *)

end

You have to write {!Ns.A}. I would like to be able to write {!A} that it renders as A but links to Ns.A.

It has been a long time since I haven't used ocamldoc but I believe it worked that way since I had to "fix" a lot of my mlis.

(I did not test with 2.0.0 yet)

[Julow]

I opened a new issue for your last comment (#594) so this issue can be closed by #592