Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0006966OCamlocamldocpublic2015-08-21 15:252017-02-22 17:07
Reportermottl 
Assigned To 
PrioritynormalSeverityfeatureReproducibilityalways
StatusacknowledgedResolutionopen 
PlatformOSOS Version
Product Version 
Target VersionundecidedFixed in Version 
Summary0006966: Cannot attach documentation to polymorphic variants
DescriptionConsider 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.
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
(0014369)
lpw25 (developer)
2015-08-21 18:32

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 *)
              -> string

  type t = int (** the first part *) * float (** the second part *)
(0014370)
mottl (reporter)
2015-08-21 21:06

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.
(0014372)
lpw25 (developer)
2015-08-22 17:30

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.
(0014373)
mottl (reporter)
2015-08-23 02:23

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.

- Issue History
Date Modified Username Field Change
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
Powered by Mantis Bugtracker