Type extensions are no anchorable and should be classified as type

[dbuenzli]

The individual cases are anchorable but the toplevel type t += isn't which is annoying when you want refer to the extension, not a particular case. I guess something must be solved to generate unique ids in that case.

Also it would be nice to classify them as spec type extension rather spec extension Since most of the rendering is going to be shared with spec type, this simplifies stylesheets. It seems to stem from this line but I'm a bit usure what will happen for generators if we replace that "extension" with "type extension" (e.g. here in the HTML generator). @Drup knows maybe ?

[Drup]

hmm, if we want to have several "kinds", we should make this a string list, instead of a string option. I think it's a good idea.

[Drup]

As choice of anchor, I suggest we use the data constructors that are being added, either a complete concatenation, or just the first one.

[dbuenzli]

As choice of anchor, I suggest we use the data constructors that are being added, either a complete concatenation, or just the first one.

That seems a good idea. Something like type-$(type)-$(first-constructor). Also is there a syntax to refer to them with the {!ref} syntax ?

hmm, if we want to have several "kinds", we should make this a string list, instead of a string option. I think it's a good idea.

Yes that's the reason why I opened an issue rather than doing it directly. That being said I'm not super happy with the markup classification in general in the content of type definitions.

Unless you want to go wild, it's likely that for most kind of type definitions the styling rules are the same. That is the classification on td (field, contstructor, extension, etc.) is not really what you want. You want classification of the kind on the container, i.e. on the table (e.g. to play with indentation of all the tds). CSS being CSS you can always workaround, but I'm always interested in keeping it as simple as possible.

Also using .doc for the docstring in types cases and .doc on a div on include is not such a good idea. (In general using the same class for vastly different contexts leads to CSS side effect pains).

Finally cut and paste is broken if you document your cases/record fields. I'm not exactly sure what the best course of actions is here. The easiest is to put the doc string in a comment like ocamldoc did. I suspect there may be a way to devise the markup so that the comments get ignored when you select them, but doing so in a browser compatible is likely to be fraught with pain.

[dbuenzli]

Finally cut and paste is broken if you document your cases/record fields.
[...]
but doing so in a browser compatible is likely to be fraught with pain.

Oddly enough it seems that CSS's user-select: none works good enough. For example appropriately applied on:

https://b0-system.github.io/odig/doc/biniou/Bi_inbuf/index.html

Results in a perfect c&p in Firefox and with one blank line added for documented fields in Chrome (but that's ok, the c&p remains valid OCaml syntax).

[Drup]

Doesn't that prevent people to c/c the documentation ?

[dbuenzli]

Yes it's a trade-off.

I argue that most of the time you are interested in c&p the defs because you want to construct (record)/deconstruct (variant) the value. In that case having the documentation crap coming along without the (** *) is rather annoying since it's not syntactically valid.

Another option would be to add the (** and *) in spans.

[dbuenzli]

Also this can be slightly mitigated by reinstating c&p on :hover in the docstrings.

[dbuenzli]

Cross referencing the issue #296 for the c&p discussion.

If #615 gets merged what remains to be done from this issue is the anchoring (I had a peek at it but the changes are likely to be a bit more involved what I can invest).

[Julow]

An anchor have been added in the generated html (#684) but it's still not possible to write a reference to them yet.
The anchor looks like extension-decl-FirstConstructor, which works as long as the constructors are not moved or removed. But I think this wouldn't work as a reference syntax.

I think references to type extensions should only mention the target type (eg. {!B."A.t+="}).
That would not allow references to the second extension to the same type but I think that's reasonable because it can be written only with knowledge of the target's source code (eg. "the second extension" or "the extension that contains this constructor").