New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Bigarray 'type kind' documentation bad layout since 4.02 #7109
Comments
Comment author: @lpw25 The addition of GADT constructors changed the comment association. It needs a (empty) doc comment on the last constructor. |
Comment author: @Octachron 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. |
Comment author: @lpw25 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. |
Comment author: @Octachron 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 #380. |
Comment author: @lpw25
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. |
Original bug ID: 7109
Reporter: @edwintorok
Assigned to: @gasche
Status: closed (set by @xavierleroy on 2017-02-16T14:18:04Z)
Resolution: fixed
Priority: normal
Severity: minor
Fixed in version: 4.03.0+dev / +beta1
Category: documentation
Bug description
http://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 information
From #ocaml:
octachron: edwin, as an information complement, the problem is with the new association rule for docstring comment on constructors
The text was updated successfully, but these errors were encountered: