|Anonymous | Login | Signup for a new account||2017-11-22 08:35 CET|
|Main | My View | View Issues | Change Log | Roadmap|
|View Issue Details|
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0006966||OCaml||ocamldoc||public||2015-08-21 15:25||2017-02-22 17:07|
|Target Version||undecided||Fixed in Version|
|Summary||0006966: Cannot attach documentation to polymorphic variants|
|Description||Consider the following example "foo.ml":|
type t =
| A (** Test *)
type u = [
| `A (** Test *)
Compiling the above with "ocamlc -w A foo.ml" will give the following warning:
File "foo.ml", line 5, characters 8-19:
Warning 50: unattached documentation comment (ignored)
Obviously, this only happens with the polymorphic variant and not the sum type. I think polymorphic variants should be treated the same way.
|Tags||No tags attached.|
The issue here is that the second form is a type equation not a type definition. It is not entirely clear why that form should be supported without also supporting:
type t = int -> [`Foo (** the foo variant *) | `Bar (** the bar variant *) ]
type t = int (** the foo parameter *)
-> float (** the bar parameter *)
type t = int (** the first part *) * float (** the second part *)
Fair enough, not sure whether the full generality of type equations should be supported. It's always possible to factor out the polymorphic variant part, e.g. with your example:
type variant = [ `Foo (** the foo variant *) | `Bar (** the bar variant *) ]
type t = int -> variant
If we allow for special treatment of the case where the polymorphic variant is "immediate", then it becomes possible to document entries individually. It would be surprising to see a tuple or function with hundreds of entries, but having large polymorphic variant types with possibly thousands of entries can actually happen in practice with auto-generated code. It would be nice then to also have some documentation for each case in the API.
My personal preference is to support something like:
(** The type t.
@variant `Foo The constructor of foos.
@variant `Bar The constructor of bars. *)
type t = [ `Foo | `Bar ]
This is slightly less convenient, but it leaves the somewhat ad-hoc decision about which parts of type equations can be documented to the documentation tool rather than the compiler.
I hope to add support for something like this to the (not yet released) codoc tool.
That's a possibility and somewhat similar to using "@param" for describing function parameters. The downside is that the documentation and the code are then separate, making it more likely that developers forget about the documentation, especially when new cases are added.
The current documentation system may not be expressive enough to fully cover all syntactic constructs. I believe there were some ideas for a standardized documentation system built on attributes as introduced in OCaml 4.02. Not sure what happened to this proposal.
|2015-08-21 15:25||mottl||New Issue|
|2015-08-21 15:25||mottl||Status||new => assigned|
|2015-08-21 15:25||mottl||Assigned To||=> guesdon|
|2015-08-21 16:09||guesdon||Assigned To||guesdon =>|
|2015-08-21 18:32||lpw25||Note Added: 0014369|
|2015-08-21 21:06||mottl||Note Added: 0014370|
|2015-08-22 17:30||lpw25||Note Added: 0014372|
|2015-08-23 02:23||mottl||Note Added: 0014373|
|2016-02-03 12:45||doligez||Status||assigned => acknowledged|
|2016-02-03 12:45||doligez||Target Version||=> 4.03.1+dev|
|2017-02-16 14:01||doligez||Target Version||4.03.1+dev => undecided|
|2017-02-22 17:07||frisch||Severity||minor => feature|
|2017-02-23 16:46||doligez||Category||OCamldoc => ocamldoc|
|Copyright © 2000 - 2011 MantisBT Group|