Mantis Bug Tracker

View Issue Details Jump to Notes ] Issue History ] Print ]
IDProjectCategoryView StatusDate SubmittedLast Update
0007109OCamldocumentationpublic2015-12-28 15:452017-02-16 15:18
Reporteredwin 
Assigned Togasche 
PrioritynormalSeverityminorReproducibilityalways
StatusclosedResolutionfixed 
PlatformOSOS Version
Product Version 
Target VersionFixed in Version4.03.0+dev / +beta1 
Summary0007109: Bigarray 'type kind' documentation bad layout since 4.02
Descriptionhttp://caml.inria.fr/pub/docs/manual-ocaml-4.01/libref/Bigarray.html#TYPEkind [^] vs
http://caml.inria.fr/pub/docs/manual-ocaml-4.02/libref/Bigarray.html#TYPEkind [^]

In 4.02 the comment seems to be associated with the last variant, and not the type as the whole, and the documentation is rendered in an unpleasant way
Additional InformationFrom #ocaml:
octachron: edwin, as an information complement, the problem is with the new association rule for docstring comment on constructors
TagsNo tags attached.
Attached Files

- Relationships

-  Notes
(0015198)
lpw25 (developer)
2015-12-28 16:05

The addition of GADT constructors changed the comment association. It needs a (empty) doc comment on the last constructor.
(0015199)
octachron (developer)
2015-12-28 16:14

Adding an empty doc comment on the last constructor fixes the association problem. However, the empty comment is printed in the html documentation as "(* *)" which is quite unsastifying.
(0015200)
lpw25 (developer)
2015-12-28 18:36
edited on: 2015-12-28 18:38

Damn ocamldoc is annoying. IIRC a blank *non-documentation* comment may do the trick -- since type comments can follow regular comments but constructor comments can't. It may be simpler to just put the comment before the type, or to add genuine documentation to the constructors.

(0015201)
octachron (developer)
2015-12-28 18:59

Unfortunately, inserting a blank normal comment detaches the documentation comment. As a solution, I have proposed to erase empty constructor comments in ocamldoc itself in https://github.com/ocaml/ocaml/pull/380. [^]
(0015202)
lpw25 (developer)
2015-12-28 23:23

> inserting a blank normal comment detaches the documentation comment

Oh yes, I forgot that the comment thing only works *before* a definition (because why would the rules be consistent).

The new documentation handling in the main parser removes these inconsistencies but unfortunately still suffers from the original issue of associating comments after variant definitions. Although at least codoc will drop empty comments.
(0015203)
gasche (administrator)
2015-12-29 13:15

Fixed in trunk by
  https://github.com/ocaml/ocaml/pull/380 [^]

- Issue History
Date Modified Username Field Change
2015-12-28 15:45 edwin New Issue
2015-12-28 16:05 lpw25 Note Added: 0015198
2015-12-28 16:14 octachron Note Added: 0015199
2015-12-28 18:36 lpw25 Note Added: 0015200
2015-12-28 18:38 lpw25 Note Edited: 0015200 View Revisions
2015-12-28 18:59 octachron Note Added: 0015201
2015-12-28 23:23 lpw25 Note Added: 0015202
2015-12-29 13:15 gasche Note Added: 0015203
2015-12-29 13:15 gasche Status new => resolved
2015-12-29 13:15 gasche Fixed in Version => 4.03.0+dev / +beta1
2015-12-29 13:15 gasche Resolution open => fixed
2015-12-29 13:15 gasche Assigned To => gasche
2017-02-16 15:18 xleroy Status resolved => closed
2017-02-23 16:35 doligez Category OCaml documentation => Documentation
2017-02-23 16:44 doligez Category Documentation => documentation


Copyright © 2000 - 2011 MantisBT Group
Powered by Mantis Bugtracker