Comment author: @Octachron

As far as I can see, there is nothing particular to inline records here: constructors comments are rendered in a separated column, and a type like

type t =
| Alpha of (a -> very -> long -> type' -> name -> leads -> to' ->exactly -> the -> same -> html -> structure) (** Comment for the Alpha constructor )
| Beta of (namely -> documentation -> comments -> for' ->constructor -> are -> rendered -> in' -> a -> separated -> column) (* another comment for the Beta constructor *)

is essentially rendered in the same way. Or I am missing what you meant by strangeness?

Comment author: kosik

You are right. This strangeness is not specific to inline records. It happens also in other situations. In this case:

type t

type u =
| Alpha of t (** TEST )
| Beta of (t -> t -> t -> t -> t -> t -> t -> t -> t -> t -> t ) (* TEST *)

I get the output shown in "test1.png".

I think that the second comment (for the "Beta" variant) is rendered in an odd way. It starts and ends on different lines and that way it looks as if part of the Ocaml code was commented out, which is not the case.

Sure, copying and pasting that we get the correct thing, but it does not look correct in a browser.

Comment author: @yawaramin

IMO, variant and record docs are overly complex, they can be greatly simplified. The first thing to do is get rid of the 'type tables', and use the same style for comments we use everywhere else. Each component of the type should be flush along the left margin, and each comment should be indented by placing it in the 'info' div as usual. Attaching a pic to show what I mean.

EDIT: actually I like Discourse's markup rendering even better: https://discuss.ocaml.org/t/proposal-ocamldoc-should-generate-a-table-of-contents-in-each-module-page/871?u=yawaramin

I think that would be a nice design refresh for the docs. But I understand that is probably out of scope here.

This issue has been open one year with no activity. Consequently, it is being marked with the "stale" label. What this means is that the issue will be automatically closed in 30 days unless more comments are added or the "stale" label is removed. Comments that provide new information on the issue are especially welcome: is it still reproducible? did it appear in other contexts? how critical is it? etc.