Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0007634OCamlocamldocpublic2017-09-20 23:302017-09-30 14:21
Reporterkosik 
Assigned To 
PrioritynormalSeverityminorReproducibilityalways
StatusacknowledgedResolutionopen 
PlatformOSOS Version
Product Version4.05.0 
Target VersionFixed in Version 
Summary0007634: ocamldoc generates strange looking documentation for variants
Description(Original title was: ocamldoc generates strange looking documentation for variants with inline records)

If I define a variant type with inline records, e.g.:

  type t = Foo of {field1 : int;
                   field2 : int;
                   field3 : int}
           (** comment 1 *)

       | Bar of {field1 : int;
                 field2 : int;
                 field3 : int}
         (** comment 2 *)

and I ask ocamldoc to generate the HTML documentation:

  ocamldoc -html test.mli

then the documentation looks strange.

The comments starts on a line that contains "{" and end on a line that contains "}".
Tagsocamldoc
Attached Filespng file icon test1.png [^] (5,388 bytes) 2017-09-21 09:32


png file icon Screen Shot 2017-09-29 at 21.53.23.png [^] (122,153 bytes) 2017-09-30 03:57

- Relationships

-  Notes
(0018301)
octachron (developer)
2017-09-20 23:45

As far as I can see, there is nothing particular to inline records here: constructors comments are rendered in a separated column, and a type like

type t =
| Alpha of (a -> very -> long -> type' -> name -> leads -> to' ->exactly -> the -> same -> html -> structure) (** Comment for the Alpha constructor *)
| Beta of (namely -> documentation -> comments -> for' ->constructor -> are -> rendered -> in' -> a -> separated -> column) (** another comment for the Beta constructor *)

is essentially rendered in the same way. Or I am missing what you meant by strangeness?
(0018304)
kosik (reporter)
2017-09-21 09:32

You are right. This strangeness is not specific to inline records. It happens also in other situations. In this case:

  type t

  type u =
  | Alpha of t (** TEST *)
  | Beta of (t -> t -> t -> t -> t -> t -> t -> t -> t -> t -> t ) (** TEST *)

I get the output shown in "test1.png".

I think that the second comment (for the "Beta" variant) is rendered in an odd way. It starts and ends on different lines and that way it looks as if part of the Ocaml code was commented out, which is not the case.

Sure, copying and pasting that we get the correct thing, but it does not *look* correct in a browser.
(0018410)
yawaramin (reporter)
2017-09-30 03:57
edited on: 2017-09-30 19:43

IMO, variant and record docs are overly complex, they can be greatly simplified. The first thing to do is get rid of the 'type tables', and use the same style for comments we use everywhere else. Each component of the type should be flush along the left margin, and each comment should be indented by placing it in the 'info' div as usual. Attaching a pic to show what I mean.

EDIT: actually I like Discourse's markup rendering even better: https://discuss.ocaml.org/t/proposal-ocamldoc-should-generate-a-table-of-contents-in-each-module-page/871?u=yawaramin [^]

I think that would be a nice design refresh for the docs. But I understand that is probably out of scope here.


- Issue History
Date Modified Username Field Change
2017-09-20 23:30 kosik New Issue
2017-09-20 23:45 octachron Note Added: 0018301
2017-09-21 09:32 kosik Note Added: 0018304
2017-09-21 09:32 kosik File Added: test1.png
2017-09-30 03:57 yawaramin Note Added: 0018410
2017-09-30 03:57 yawaramin File Added: Screen Shot 2017-09-29 at 21.53.23.png
2017-09-30 10:24 xleroy Status new => acknowledged
2017-09-30 10:24 xleroy Summary ocamldoc generates strange looking documentation for variants with inline records => ocamldoc generates strange looking documentation for variants
2017-09-30 10:24 xleroy Description Updated View Revisions
2017-09-30 14:21 yawaramin Tag Attached: ocamldoc
2017-09-30 19:42 yawaramin Note Edited: 0018410 View Revisions
2017-09-30 19:43 yawaramin Note Edited: 0018410 View Revisions


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker