-
Notifications
You must be signed in to change notification settings - Fork 1.1k
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
PR#7478: ocamldoc, avoid module preamble repetition #1037
Conversation
6302f5b
to
754813c
Compare
Changes
Outdated
- PR#7478, GPR#1037: ocamldoc, do not use as a module preamble documentation | ||
comments that occur after the first module element | ||
(Florian Angeletti, report by Daniel Bünzli) | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Doesn't this qualify as a breaking change (even if a good one)?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It does not seem completely clear-cut to me since documentations affected by the change were already somehow broken. Nevertheless, erring on the side of caution and adding a warning about open statements is probably better.
ocamldoc/odoc_sig.ml
Outdated
| a :: _ when a.Parsetree.psig_loc.Location.loc_start.Lexing.pos_cnum < | ||
fst info -> | ||
(0,None) | ||
| _ -> info in |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is it possible to refactor this to remove the small code duplication with odoc_ast.ml?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Possible, certainly. Optimal, I am not so sure, see d7269c0 .
To avoid module preamble repetition, ocamldoc only use as a module preamble documentation comments that occur before any module elements, which should also prevent some unexpected module preamble when the first documentation comments appears in the middle of the source file.
92ff0fc
to
64d9cee
Compare
64d9cee
to
3bf7f9f
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Previous review comments addressed - all looks good to me
Nice work, thanks! |
Revert "Use Import_info.t in Cmt_format (ocaml#1037)" This reverts commit 2798499.
Co-authored-by: Cuihtlauac ALVARADO <cuihtmlauac@tarides.com>
MPR#7478:
Currently, ocamldoc uses the first documentation comment in a source file as a module preamble. This has the unfortunate consequence that ocamldoc can use documentation comments far from the start of the file as a preamble. Moreover, if this first documentation comment occurs after any module element, this documentation comment will appear twice in the generated documentation: first as a module preamble, then at its original position in the source file:
This PR proposes to fix this duplication of documentation comments by using as module preamble, only documentation comments that appear before any module elements: