Skip to content
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

Closed
vicuna opened this issue Dec 28, 2015 · 6 comments
Closed

Bigarray 'type kind' documentation bad layout since 4.02 #7109

vicuna opened this issue Dec 28, 2015 · 6 comments
Assignees

Comments

@vicuna
Copy link

vicuna commented Dec 28, 2015

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

@vicuna
Copy link
Author

vicuna commented Dec 28, 2015

Comment author: @lpw25

The addition of GADT constructors changed the comment association. It needs a (empty) doc comment on the last constructor.

@vicuna
Copy link
Author

vicuna commented Dec 28, 2015

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.

@vicuna
Copy link
Author

vicuna commented Dec 28, 2015

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.

@vicuna
Copy link
Author

vicuna commented Dec 28, 2015

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.

@vicuna
Copy link
Author

vicuna commented Dec 28, 2015

Comment author: @lpw25

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.

@vicuna
Copy link
Author

vicuna commented Dec 29, 2015

Comment author: @gasche

Fixed in trunk by
#380

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants