Confusing origin of "aliased" type in submodule

[MisterDA]

dune configurator has this code:

module V1 : sig
  type t
  module Pkg_config : sig
    type configurator = t

    type t

    (** Search pkg-config in the PATH. Returns [None] if pkg-config is not found. *)
    val get : configurator -> t option
  end
end

which gets rendered in the V1.Pkg_config module as

I find it confusing that although the first t points to the parent's module t type, this is really not clear in the user interface. Users may click or hover on the type parameter to understand that the type comes from above. Maybe a disambiguating prefix path could be added in such cases? or retain the alias?

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. The main purpose of this is to keep the issue tracker focused to what is actively being worked on, so that the amount and variety of open yet inactive issues does not overwhelm contributors.

An issue closed as stale is not rejected — further discussion is welcome in its closed state, and it can be resurrected at any time. odoc maintainers regularly check issues that were closed as stale in the past, to see if the time is right to reopen and work on them again. PRs addressing issues closed as stale are as welcome as PRs for open issues. They will be given the same review attention, and any other help.

[panglesd]

I tried the minimal reproduction example and the problem is not visible:

However, in your actual case, the problem is still there: see for instance https://ocaml.org/p/dune-configurator/latest/doc/Configurator/V1/Pkg_config/index.html

[panglesd]

Since I am in a train with @MisterDA, I had another look at this issue.

The minimal example should include a destructive substitution:

module V1 : sig
  type t
  module Pkg_config : sig
    type configurator = t

    type t

    (** Search pkg-config in the PATH. Returns [None] if pkg-config is not found. *)
    val get : configurator -> t option
  end with type configurator := t
end

The issue is very similar to #961. When a type is removed from a signature, either with (**/**) type alias := t (**/**) as in #961 or by with type alias := t as in this issue, we might face the problem of name clashes.

I don't think using a fully-qualified name would work: in your example the fully qualified name would be V1.t, but what if this path also exists in the current module? (eg V1.Pkg_config.V1.t?).

In the meantime a better name is found and used (t/2?), a solution could be to not replace configurator by t, but replace the type definition by a type destruction, so that it would render the same as:

module V1 : sig
  type t
  module Pkg_config : sig
    type configurator := t

    type t

    (** Search pkg-config in the PATH. Returns [None] if pkg-config is not found. *)
    val get : configurator -> t option
  end
end