Warnings about ambigous references are bogus

[jonludlam]

example:

Reference to 'enqueue' is ambiguous. Please specify its kind: val-enqueue, val-enqueue.

These are seen in many packages so should be easy to repro. I wonder if it's because we have the value enqueue defined in different modules, both in scope?

[dbuenzli]

One occurence where that happens is in the following case:

val the_fun : …

module Special : sig

   val the_fun : …
   (** [the_fun] is like {!the_fun} but … *)

end

In this case you get:

Reference to 'the_fun' is ambiguous. Please specify its kind: val-the_fun, val-the_fun.

In this case the warning is not bogus, but the suggestion does not fix anything.

[dbuenzli]

Note also that nowadays it also warns if in the above the the_fun comes after the Special module. I think it did not before so that may be one of the reasons why you see a lot of these ambiguous references.

In general I think it would be time for 2.0.0 to properly define the notion of scope for odoc. See #594, #332, #42.

It should also be noted that in ocamldoc if you had ambiguities with say a section and a value it would simply default to link to the value. That difference should be documented. I don't think ocamldoc's behaviour was good because it meant that links could change without you noticing (e.g. when you had an id section to which you referred and then later you add an id value to your module).