Merged
Conversation
Odoc now strips the indentation from code and verbatim blocks. It doesn't use the indentation of the least indented line, like OCamlformat, but instead use the indentation of the block opening.
In code blocks, newlines can be turned into `\\n` (or the opposite) when formatting string literals that need to break. Update the normalization function to avoid crashing when that happens.
The updated Odoc parser considers that code blocks horizontally start at the opening bracket. It no longer uses the indentation of the least indented line for that. As a result, OCamlformat cannot indent code blocks without changing their content. The indentation is also removed in code blocks that are formatted, to avoid adding visible indentation in rendered documentation.
During normalisation, allow whitespaces to disappear from code blocks. This happens when code if formatted.
Julow
added a commit
to Julow/opam-repository
that referenced
this pull request
Mar 17, 2026
CHANGES: ### Highlight - \* Support OCaml 5.5 syntax (ocaml-ppx/ocamlformat#2772, ocaml-ppx/ocamlformat#2774, ocaml-ppx/ocamlformat#2775, ocaml-ppx/ocamlformat#2777, ocaml-ppx/ocamlformat#2780, ocaml-ppx/ocamlformat#2781, ocaml-ppx/ocamlformat#2782, ocaml-ppx/ocamlformat#2783, @Julow) The update brings several tiny changes, they are listed below. - \* Update Odoc's parser to 3.0 (ocaml-ppx/ocamlformat#2757, @Julow) The indentation of code-blocks containing OCaml code is reduced by 2 to avoid changing the generated documentation. The indentation within code-blocks is now significative in Odoc and shows up in generated documentation. ### Added - Added option `letop-punning` (ocaml-ppx/ocamlformat#2746, @WardBrian) to control whether punning is used in extended binding operators. For example, the code `let+ x = x in ...` can be formatted as `let+ x in ...` when `letop-punning=always`. With `letop-punning=never`, it becomes `let+ x = x in ...`. The default is `preserve`, which will only use punning when it exists in the source. This also applies to `let%ext` bindings (ocaml-ppx/ocamlformat#2747, @WardBrian). - Support the unnamed functor parameters syntax in module types (ocaml-ppx/ocamlformat#2755, ocaml-ppx/ocamlformat#2759, @Julow) ```ocaml module type F = ARG -> S ``` The following lines are now formatted as they are in the source file: ```ocaml module M : (_ : S) -> (_ : S) -> S = N module M : S -> S -> S = N (* The preceding two lines are no longer turned into this: *) module M : (_ : S) (_ : S) -> S = N ``` ### Fixed - Fix dropped comment in `(function _ -> x (* cmt *))` (ocaml-ppx/ocamlformat#2739, @Julow) - \* `cases-matching-exp-indent=compact` does not impact `begin end` nodes that don't have a match inside. (ocaml-ppx/ocamlformat#2742, @EmileTrotignon) ```ocaml (* before *) begin match () with | () -> begin f x end end (* after *) begin match () with | () -> begin f x end end ``` - `Ast_mapper` now iterates on *all* locations inside of Longident.t, instead of only some. (ocaml-ppx/ocamlformat#2737, @v-gb) - Remove line break in `M with module N = N (* cmt *)` (ocaml-ppx/ocamlformat#2779, @Julow) ### Internal - Added information on writing tests to `CONTRIBUTING.md` (ocaml-ppx/ocamlformat#2838, @WardBrian) ### Changed - indentation of the `end` keyword in a match-case is now always at least 2. (ocaml-ppx/ocamlformat#2742, @EmileTrotignon) ```ocaml (* before *) begin match () with | () -> begin match () with | () -> () end end (* after *) begin match () with | () -> begin match () with | () -> () - \* use shortcut `begin end` in `match` cases and `if then else` body. (ocaml-ppx/ocamlformat#2744, @EmileTrotignon) ```ocaml (* before *) match () with | () -> begin match () with | () -> end end (* after *) match () with | () -> begin match () with | () -> end end ``` - \* Set the `ocaml-version` to `5.4` by default (ocaml-ppx/ocamlformat#2750, @EmileTrotignon) The main difference is that the `effect` keyword is recognized without having to add `ocaml-version=5.3` to the configuration. In exchange, code that use `effect` as an identifier must use `ocaml-version=5.2`. - The work to support OCaml 5.5 come with several improvements: + Improve the indentation of `let structure-item` with the `[@ocamlformat "disable"]` attribute. `let structure-item` means `let module`, `let open`, `let include` and `let exception`. + `(let open M in e)[@A]` is turned into `let[@A] open M in e`. + Long `let open ... in` no longer exceed the margin. + Improve indentation of `let structure-item` within parentheses: ```ocaml (* before *) (let module M = M in M.foo) (* after *) (let module M = M in M.foo) ```
Julow
added a commit
to Julow/opam-repository
that referenced
this pull request
Mar 17, 2026
CHANGES: ### Highlight - \* Support OCaml 5.5 syntax (ocaml-ppx/ocamlformat#2772, ocaml-ppx/ocamlformat#2774, ocaml-ppx/ocamlformat#2775, ocaml-ppx/ocamlformat#2777, ocaml-ppx/ocamlformat#2780, ocaml-ppx/ocamlformat#2781, ocaml-ppx/ocamlformat#2782, ocaml-ppx/ocamlformat#2783, @Julow) The update brings several tiny changes, they are listed below. - \* Update Odoc's parser to 3.0 (ocaml-ppx/ocamlformat#2757, @Julow) The indentation of code-blocks containing OCaml code is reduced by 2 to avoid changing the generated documentation. The indentation within code-blocks is now significative in Odoc and shows up in generated documentation. ### Added - Added option `letop-punning` (ocaml-ppx/ocamlformat#2746, @WardBrian) to control whether punning is used in extended binding operators. For example, the code `let+ x = x in ...` can be formatted as `let+ x in ...` when `letop-punning=always`. With `letop-punning=never`, it becomes `let+ x = x in ...`. The default is `preserve`, which will only use punning when it exists in the source. This also applies to `let%ext` bindings (ocaml-ppx/ocamlformat#2747, @WardBrian). - Support the unnamed functor parameters syntax in module types (ocaml-ppx/ocamlformat#2755, ocaml-ppx/ocamlformat#2759, @Julow) ```ocaml module type F = ARG -> S ``` The following lines are now formatted as they are in the source file: ```ocaml module M : (_ : S) -> (_ : S) -> S = N module M : S -> S -> S = N (* The preceding two lines are no longer turned into this: *) module M : (_ : S) (_ : S) -> S = N ``` ### Fixed - Fix dropped comment in `(function _ -> x (* cmt *))` (ocaml-ppx/ocamlformat#2739, @Julow) - \* `cases-matching-exp-indent=compact` does not impact `begin end` nodes that don't have a match inside. (ocaml-ppx/ocamlformat#2742, @EmileTrotignon) ```ocaml (* before *) begin match () with | () -> begin f x end end (* after *) begin match () with | () -> begin f x end end ``` - `Ast_mapper` now iterates on *all* locations inside of Longident.t, instead of only some. (ocaml-ppx/ocamlformat#2737, @v-gb) - Remove line break in `M with module N = N (* cmt *)` (ocaml-ppx/ocamlformat#2779, @Julow) ### Internal - Added information on writing tests to `CONTRIBUTING.md` (ocaml-ppx/ocamlformat#2838, @WardBrian) ### Changed - indentation of the `end` keyword in a match-case is now always at least 2. (ocaml-ppx/ocamlformat#2742, @EmileTrotignon) ```ocaml (* before *) begin match () with | () -> begin match () with | () -> () end end (* after *) begin match () with | () -> begin match () with | () -> () - \* use shortcut `begin end` in `match` cases and `if then else` body. (ocaml-ppx/ocamlformat#2744, @EmileTrotignon) ```ocaml (* before *) match () with | () -> begin match () with | () -> end end (* after *) match () with | () -> begin match () with | () -> end end ``` - \* Set the `ocaml-version` to `5.4` by default (ocaml-ppx/ocamlformat#2750, @EmileTrotignon) The main difference is that the `effect` keyword is recognized without having to add `ocaml-version=5.3` to the configuration. In exchange, code that use `effect` as an identifier must use `ocaml-version=5.2`. - The work to support OCaml 5.5 come with several improvements: + Improve the indentation of `let structure-item` with the `[@ocamlformat "disable"]` attribute. `let structure-item` means `let module`, `let open`, `let include` and `let exception`. + `(let open M in e)[@A]` is turned into `let[@A] open M in e`. + Long `let open ... in` no longer exceed the margin. + Improve indentation of `let structure-item` within parentheses: ```ocaml (* before *) (let module M = M in M.foo) (* after *) (let module M = M in M.foo) ```
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #2702
The indentation of code-blocks containing OCaml code is reduced by 2 to avoid changing the generated documentation. The indentation within code-blocks is now significative in Odoc and shows up in generated documentation.