[wg-camlp4] Structure/signature attributes suggestion

[Leo White]

Hi,

I've been looking recently at encoding inline documentation
(i.e. ocamldoc comments) within attributes, as part of my work on
opam-doc. Mostly this works fine, but there is an issue with comments
that are not attached to any item (e.g. section headers).

I had thought that the existing support for "structure/signature
attributes" would be sufficient. By these I mean attributes like:

  ;;[@@doc "Hello World"]

which are parsed as separate structure/signature items rather than
attached to an existing structure/signature item.

The problem is that unattached attributes can appear in a number of
places that structure attributes cannot. Some examples:

  type t = Foo of s

  (** {3 Section} *)

  and s = Bin of t option

  class type foo = object
    method a : int

    (** Some comment *)

    method b : int
  end

and so on.

In both these cases it is hard to add support for structure items in
those locations because that would require supporting ';;' in those
locations as well.

I have also heard a number of complaints about the ";;[@@ foo]"
syntax. Firstly, that it is ugly and its meaning is not particularly
obvious, and secondly that users may be confused when

  type t;;
  [@@ sexp]

silently does not work.

So my suggestion would be to (reluctantly) add a third form of
attribute:

  [@@@ foo]

which means basically the same as:

 ;;[@@ foo]

does now. This could be supported in the additional locations that I
mentioned above, and would allow for a syntax error for the ";;[@@sexp]"
mistake.

Since this follows the existing pattern of [@...] and [@@...], it should
not be too much trouble to tell users about [@@@ ...], and certainly no
worse than explaining ";;[@@...]" to them.

Regards,

Leo