References through `open`

[Julow]

Currently there is no support for unqualified references to items brought into the scope by an open. This was reported by @dbuenzli: https://github.com/ocaml/odoc/issues/585#issuecomment-777599121

For example:

module A : sig
  type t
end

open A (* We currently ignore this, internally we have a [Lang.Open.t] with [expansion = []]. *)

type u = t (* This works as expected and renders as [A.t] because OCaml resolves it for us. *)

(** {!t} This doesn't resolve. *)

Expected behavior ?

open A

(** {!t} *)

In this example, should t resolve and should it render as t (as it's written) or A.t (as it would renders if it were a type expression) ?

What about this:

(** {!t} *)

open A

References can point to items defined below them, and even to included items. Should open have the same behavior ?

Fixing this issue would probably break one of:

• References renders as they are written
• References renders to valid paths that could be typed checked again

[dbuenzli]

In this example, should t resolve and should it render as t (as it's written) or A.t (as it would renders if it were a type expression) ?

In my opinion it should render as t – in general, as written. For these reasons:

1. This allows to make some signatures less heavyweight. In particular for those definitions that draw from modules that are in a namespacing module, it allows to elide the latter. The actual link will still get to the exact place (we could also consider writing the full reference in a tooltip), so it shouldn't be confusing.
2. You still have the choice to make it render as A.t by using {!A.t}.

Expected behavior ?

In general it's nice that ocamldoc language allows forwards references, but it's still unclear to me how these work exactly, it would be nice to have formal documentation about the exact notion of scope of the ocamldoc language and how it differs with the one from OCaml.

In any case I don't feel the need to go overboard with differences and in general it seems wise to keep the notion of scope of OCaml and ocamldoc as close as possible. Besides I highly suspect that:

(** {!t} *)

open A

wouldn't work in ocamldoc (I didn't check) and I don't think it's such a good idea to support it.