Comment author: @lpw25

The issue here is that the second form is a type equation not a type definition. It is not entirely clear why that form should be supported without also supporting:

  type t = int -> [`Foo (** the foo variant *) | `Bar (** the bar variant *) ]

  type t = int (** the foo parameter *)
             -> float (** the bar parameter *)
              -> string

  type t = int (** the first part *) * float (** the second part *)

Comment author: @mmottl

Fair enough, not sure whether the full generality of type equations should be supported. It's always possible to factor out the polymorphic variant part, e.g. with your example:

  type variant = [ `Foo  (** the foo variant *) | `Bar (** the bar variant *) ]
  type t = int -> variant

If we allow for special treatment of the case where the polymorphic variant is "immediate", then it becomes possible to document entries individually. It would be surprising to see a tuple or function with hundreds of entries, but having large polymorphic variant types with possibly thousands of entries can actually happen in practice with auto-generated code. It would be nice then to also have some documentation for each case in the API.

Comment author: @lpw25

My personal preference is to support something like:

  (** The type t.
      @variant `Foo The constructor of foos.
      @variant `Bar The constructor of bars. *)
   type t = [ `Foo | `Bar ]

This is slightly less convenient, but it leaves the somewhat ad-hoc decision about which parts of type equations can be documented to the documentation tool rather than the compiler.

I hope to add support for something like this to the (not yet released) codoc tool.

Comment author: @mmottl

That's a possibility and somewhat similar to using @param for describing function parameters. The downside is that the documentation and the code are then separate, making it more likely that developers forget about the documentation, especially when new cases are added.

The current documentation system may not be expressive enough to fully cover all syntactic constructs. I believe there were some ideas for a standardized documentation system built on attributes as introduced in OCaml 4.02. Not sure what happened to this proposal.

This is a duplicate of #4347.

What's more, it's been fixed by #477.

That is, the compiler side of things has been fixed: the docstring is now attached as an attributed in the AST.
Additionally, I doubt that any work will happen on ocamldoc related to that issue (but it should happen on odoc.