What about comments inside code (like in the middle of a function) ? Iirc, ocamldoc supports those (with the weird "literate programming" mode for `.ml files).

Otherwise, the documentation is quite clear. :)

One thing I find odd is that this new section does not mention ocamldoc at all. Given that ocamldoc is also reference in the manual, I would expect the section to reference the ocamldoc documentation and explain the distinction between them, and possibly also a backreference from the ocamldoc document ("Since 4.03, ..."). In particular, you should explicitly mention the fact that ocamldoc and the parsing of documentation comments by the compiler and by ocamldoc are different. (Is one a strict subset of the other?)

I also wonder whether we should have this as a "Language Extension". This is a section where we put everything, and it's not very easy to find for non-language-experts. Could we at least have a mention of this new section in the main part of the manual that describes the grammar of the language? Could we consider having all of it outside the "Extensions" section?

Concerning the interaction between label and item comments, I think it might be nice to precise that it is possible to add an item comment after the last label comments, i.e. that

type t = Label (** label *)
(** item *)

attaches the comment (** item *) to t:

type t =
  | Label [@ocaml.doc " label "][@@ocaml.doc " item "]

On this subject, it is intended that the empty comment trick on the last label

type t = Label (**)
(** item *)

does not work anymore and generates

type t =
  | Label [@ocaml.doc " item "]

?

I've added a reference to ocamldoc and mentioned that the forms accepted by the compiler are a subset of the forms accepted by ocamldoc.

As for whether this should go in "Language extensions", I think it should go wherever the description of attributes goes since it is just an additional attribute syntax. Since that is currently in language extensions this section should also go in language extensions.

Concerning the interaction between label and item comments, I think it might be nice to precise that it is possible to add an item comment after the last label comments

Good idea. Done.

On this subject, it is intended that the empty comment trick on the last label

type t = Label (**)
(** item *)

does not work anymore and generates

(**)is not recognised as a documentation comment. Using (** *) works. It might also be good to support (**) specifically for this case. Feel free to make a feature request on Mantis.