Renderers: allow for unqualified identifier rendering

[dbuenzli]

I'm sure this is going to be controversial but I'll put it in to see what the mood is.

In general odoc html rendered specifications are much less readable than the .mli they were generated from. The reason is that we get all the prefixes from the namespacing modules they belong to. This is precise but effectively, in a given context, these tend to become noise.

I'd like to suggest to render identifiers mostly as they are found in the .mli, that is strip the open modules at most until the first prefix (so that we never get fully unqualified identifiers except for the built-in types).

Following the links allows to make clear exactly what the identifier is about and optionally we could use a name attribute so that a tooltip reveals the fully qualified identifier.

I'm sure people are going to suggest we could put that under a cli flag. I suggest we do not do so because in general when you devise docs you need a fair idea on how things are going to be presented.

A few things that are related to that:

• Rendering of references through open #594
• Remove Stdlib prefix #562

[Drup]

First off: it's not specific to the HTML renderer. All those decisions are taken when translating the model into the document IR, so it's common to all renderer.

Now, I mostly agree with you. We need to be careful about shadowing though. The tooltip idea is a good one. It does require some model changes to keep track of scopes, which might not be so easy.

[lpw25]

We've always intended to include opens in the output and then shorten the names accordingly. I'm a bit nervous about doing the shortening without also including the opens.

Whilst it is definitely an ad-hoc rule, I'd be happy to use your suggestion for all open! whilst including the open in the docs for all other opens. That would work extremely well with Jane Street's style.

[avsm]

I do think the opens need to be included in the output if the names are stripped, but that's a good opportunity in the output to cross-reference to the module being opened as the reader goes through the interface...

[dbuenzli]

I'd still like #594 be solved regardless of opens being rendered (note this is not about signature). It's quite annoying at the moment since I have to qualify a lot of my references that didn't need it before – and I'd rather not have that qualification in the end.

[trefis]

I'd like to suggest to render identifiers mostly as they are found in the .mli, that is strip the open modules at most until the first prefix (so that we never get fully unqualified identifiers except for the built-in types).

That sounds nice, but I don't think it would work well in presence of includes. Consider this artificial example:

• foo.mli and bar.mli both containing a type t
• a.mli:

  open Foo
  
  val something: t -> int -> int
  
  module Consumer : sig
   val consume_foo : t -> unit
   val consume_bar : Bar.t -> unit
  end
  
  (* ... *)
  

• b.mli:

  open Bar
  
  val something : t -> int -> int
  
  include Foo.Consumer (** @inline *)
  

What would the doc of B look like?

I think if we want something nice, we're going to have to keep track of currently opened modules, and do the shortening ourselves. (That ought to be much easier than the compiler's -short-path work though)

[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.