Doc comments on function parameters

[lukemaurer]

It would be nice to attach an odoc comment to a function parameter rather than having to mention each parameter in the comment for the whole function. Something like:

(** Do the special thing. *)
val do_it :
  (** What does the thing *)
  t ->
  (** What the thing is done to *)
  target:t ->
  (** The special sauce to use *)
  sauce:Sauce.t ->
  unit

(There's already a wrinkle in that putting the arrows at the starts of lines would would probably cause the comments to attach to different parameters.)

[lpw25]

I had thought that the compiler already collected these, but looking at the parser it seems not. I think that the attachment rules consistent with the existing ones would have it as:

(** Do the special thing. *)
val do_it :
  t -> (** What does the thing *)
  target:t ->  (** What the thing is done to *)
  sauce:Sauce.t -> (** The special sauce to use *)
  unit

and also including support for:

(** Do the special thing. *)
val do_it :
  t (** What does the thing *)
  -> target:t  (** What the thing is done to *)
  -> sauce:Sauce.t (** The special sauce to use *)
  -> unit

similar to how it's done for ; in records and object types.

[lukemaurer]

Makes sense. Certainly, consistency with record syntax is ideal.

[trefis]

The attachment rules are indeed "incomplete": they are only there for labelled/optional parameters. But for those they are already there, and it would be nice if odoc propagated them already.