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

Camlp4o messes with comments #4713

Closed
vicuna opened this issue Feb 10, 2009 · 7 comments
Closed

Camlp4o messes with comments #4713

vicuna opened this issue Feb 10, 2009 · 7 comments
Milestone

Comments

@vicuna
Copy link

vicuna commented Feb 10, 2009

Original bug ID: 4713
Reporter: Yoric
Assigned to: @diml
Status: closed (set by @diml on 2013-12-24T08:50:11Z)
Resolution: reopened
Priority: normal
Severity: minor
Version: 3.11.0
Target version: 4.01.1+dev
Category: -for Camlp4 use https://github.com/ocaml/camlp4/issues
Tags: patch
Related to: #4346 #4545
Monitored by: @ygrek kanig @hcarty @Chris00

Bug description

Camlp4o messes with comments, hence with ocamldoc generation of documentation.

In order for comments to be used by ocamldoc, they should come immediately before or after a value. Camlp4o moves comments away from values, hences breaks ocamldoc.

While there may be workarounds, it's quite annoying for documentation generation of Batteries Included, as it produces pages such as http://batteries.forge.ocamlcore.org/doc.preview:batteries-alpha3/html/api/GZip.html .

Is there any hope that this could be fixed?

File attachments

@vicuna
Copy link
Author

vicuna commented Feb 10, 2009

Comment author: Yoric

camlp4o t.mli => the comment is removed

@vicuna
Copy link
Author

vicuna commented Feb 10, 2009

Comment author: Yoric

camlp4o t2.mli => the first comment is moved from the first value to the second value, the second comment is removed

@vicuna
Copy link
Author

vicuna commented Dec 31, 2009

Comment author: @ygrek

camlp4.diff - a dirty workaround that will partially fix observed behaviour (for interface files). Can't think of anything better unless comments become part of the Ast (why not?).

@vicuna
Copy link
Author

vicuna commented Oct 27, 2010

Comment author: @ygrek

Here is one more example : http://extunix.forge.ocamlcore.org/api/ExtUnixSpecific.html#TYPEadvice

Is it possible to make comments part of the AST and will you consider such patch for inclusion?

@vicuna
Copy link
Author

vicuna commented Jan 5, 2012

Comment author: @diml

Note that the problem is that you are using an intermediate on-disk file, camlp4 is not supposed to be used like this (you loose locations for example).

If you call ocamldoc on the file before it is preprocessed with the right -pp option, then the result is fine (i tried for extunix). A possible solution for extunix is to copy extUnix.mlpp to extUnixAll.ml and extUnixSpecific.ml and use camlp4 on both files. If you want i can provide a patch.

@vicuna
Copy link
Author

vicuna commented Jan 5, 2012

Comment author: @ygrek

Thanks for looking into it - I will try to generate docs with simultaneous preprocessing and see how it goes. The generated files are included in distribution so I decided to generate docs from that files without much thinking.
(Anyway, camlp4 ideally shouldn't mess with comments).

@vicuna
Copy link
Author

vicuna commented Dec 22, 2013

Comment author: @ygrek

forwarded to camlp4/camlp4#6

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

1 participant