Merge branch 'MAIN' into cmts-factor

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: OCaml Community Forum
+    url: https://discuss.ocaml.org/
+    about: Please ask and answer questions here.
+  - name: OCaml Community Discord
+    url: https://discord.gg/cCYQbqN
+    about: Please ask and answer questions here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -2,7 +2,7 @@
 name: Feature request
 about: Suggest an idea for this project
 title: 'Feature request: ...'
-labels: Kind/Feature-request
+labels: 'Kind/feature-request'
 assignees: ''
 
 ---

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,14 @@
+---
+name: Question
+about: Do you have a question about ocamlformat?
+title: 'Question: ...'
+labels: 'Kind/question'
+assignees: ''
+
+---
+
+Please give as much context as possible.
+
+Is your question related to a specific OCaml version?
+Is your question related to a specific OCamlFormat version?
+Is your question related to a specific formatting profile or option?

.github/ISSUE_TEMPLATE/style_suggestion.md

@@ -0,0 +1,18 @@
+---
+name: Style suggestion
+about: Suggest a different formatting style for this project
+title: 'Style suggestion: ...'
+labels: 'Kind/style-suggestion'
+assignees: ''
+
+---
+
+**Current formatting**
+Please copy-paste your code and the formatting that is currently applied to it.
+
+**Describe the formatting you'd like**
+A clear and concise description of what you want to happen.
+
+**Additional context**
+Add any other context about the style request here.
+What justifies ocamlformat adding this new style?

.ocamlformat

@@ -1,6 +1,5 @@
 profile = ocamlformat
 break-cases = fit
 margin = 77
-parse-docstrings = true
 wrap-comments = true
 line-endings = lf

CHANGES.md

@@ -9,10 +9,19 @@ profile. This started with version 0.26.0.
 ### Changed
 
 - \* Consistent formatting of comments (#2371, @Julow)
+- Documentation comments are now formatted by default (#2390, @Julow)
+  Use the option `parse-docstrings = false` to disable.
+- \* Janestreet profile: do not break `fun _ -> function` (#2460, @tdelvecchio-jsc)
+- \* Reduce the indentation of (polytype) type constraints (#2437, @gpetiot)
 
 ### Fixed
 
 - Remove trailing space inside a wrapping empty signature (#2443, @Julow)
+- Fix extension-point spacing in structures (#2450, @Julow)
+- \* Consistent break after string constant argument (#2453, @Julow)
+- Fix invalid syntax generated with `ocp-indent-compat` (#2445, @Julow)
+- Fixed bug with attributes on sub-expressions of infix operators (#2459, @tdelvecchio-jsc)
+- \* Fix cinaps comment formatting to not change multiline string contents (#2463, @tdelvecchio-jsc)
 
 ## 0.26.1 (2023-09-15)
 
@@ -132,6 +141,7 @@ profile. This started with version 0.26.0.
 - JaneStreet profile: doesn't align infix ops with open paren (#2204, @gpetiot)
 - Re-use the type let_binding from the parser instead of value_binding, improve the spacing of let-bindings regarding of having extension or comments (#2219, @gpetiot)
 - The `ocamlformat` package now only contains the binary, the library is available through the `ocamlformat-lib` package (#2230, @gpetiot)
+- The position of module and module type attributes is now preserved. (#2451, #2455, @emiletrotignon)
 
 ### Added
 

doc/configuration.mld

@@ -0,0 +1,50 @@
+{0 How OCamlFormat computes its configuration}
+
+{1 Configuration files}
+
+Ocamlformat fetches the following files on the file system:
+
+1. [.git], [.hg] or [dune-project]
+2. [.ocamlformat] and [.ocp-indent]
+3. [.ocamlformat-ignore] and [.ocamlformat-enable]
+
+(1.) files are used to determine the {b project root}, which can be overriden by the [--root] option, they are looked up from the path of the file to format, and upwards following parent directories, until the first one is found.
+
+(2.) and (3.) are looked up from the path of the file to format, and following up the parents up to the project root.
+
+(2.) are the {b configuration files}, they contain the options used to configure ocamlformat. A global [.ocamlformat] file can also be used: [$XDG_CONFIG_HOME/ocamlformat] (if defined).
+
+
+{1 How the configuration is built}
+
+The configuration files are considered in sequence, starting from the root of the project, and down to the directory of the file to format, overriding one or many options at each application.
+
++ The initial configuration is equal to the [default] (or [conventional]) profile.
++ The options passed through the configuration files are applied.
++ The options passed through the [OCAMLFORMAT] environment variable are applied, overriding one or many options at a time.
++ The options passed through the command line are applied, overriding one or many options at a time.
+
+When the option [--enable-outside-detected-project] is set, [.ocamlformat] files outside of the project are read, if no [.ocamlformat] file has been found then then apply the global configuration [$XDG_CONFIG_HOME/ocamlformat] (if defined). The global configuration file is ignore in any other case.
+
+When this option is not set, [.ocamlformat] files outside of the project are ignored.
+
+If no configuration file is found, the formatting is disabled.
+
+{1 Overriding the configuration in the source}
+
+Note that some options can be overriden directly in the source, with attributes like:
+
+{@ocaml[
+(* attributes attached to algebraic constructs *)
+x [@ocamlformat "option=value,option=value"];;
+
+(* item attributes, attached to "blocks" *)
+y [@@ocamlformat "option=value,option=value"];;
+
+(* floating attributes, standalone *)
+[@@@ocamlformat "option=value,option=value"]
+]}
+
+All "formatting options" (listed in the {{!page-manpage_ocamlformat}manpage}) can be set in attributes.
+
+Among the non-formatting options only [enable]/[disable] can be set in floatting attributes.

doc/editor_setup.mld

@@ -3,6 +3,7 @@
 {1 Enable formatting outside project}
 
 OCamlFormat detects your current project if there is a [.git], a [.hg] or a [dune-project] file in one of the ancestry directories.
+For more details, read about {{!page-configuration}how OCamlFormat finds its root project and computes its configuration}.
 
 By default, when the option [--enable-outside-detected-project] is not set, [.ocamlformat] files outside of the current project (including the one in [XDG_CONFIG_HOME]) are not read. If no configuration file is found, then the formatting is disabled.
 

doc/getting_started.mld

@@ -72,12 +72,7 @@ Options can be modified by the means of:
 - a global [[@@@ocamlformat "option=VAL"]] attribute in the processed file
 - an [[@@ocamlformat "option=VAL"]] attribute on an expression in the processed file
 
-[.ocamlformat] files in the containing and all ancestor directories for each input file are used, as well as the global [.ocamlformat] file defined in [$XDG_CONFIG_HOME/ocamlformat]. The global [.ocamlformat] file has the lowest priority, then the closer the directory is to the processed file, the higher the priority.
-
-When the option [--enable-outside-detected-project] is set, [.ocamlformat] files outside of the project (including the one in [XDG_CONFIG_HOME]) are read. The project root of an input file is taken to be the nearest ancestor directory that contains a [.git] or [.hg] or [dune-project] file.
-When this option is not set, [.ocamlformat] files outside of the project are ignored. If no configuration file is found, formatting is disabled.
-
-An [.ocamlformat-ignore] file specifies files that OCamlFormat should ignore. Each line in an [.ocamlformat-ignore] file specifies a filename relative to the directory containing the [.ocamlformat-ignore] file. Lines starting with [#] are ignored and can be used as comments.
+For more details, read about {{!page-configuration}how OCamlFormat finds its root project and computes its configuration}.
 
 {1 Version}
 

doc/index.mld

@@ -9,6 +9,7 @@ OCamlFormat is a tool to format OCaml code.
 
 {1 Table of Content}
 - {{!page-getting_started}Getting started}
+- {{!page-configuration}How OCamlFormat computes its configuration}
 - {{!page-editor_setup}Editor setup}
 - {{!page-manpage_ocamlformat}Manpage}
 - {{!page-howtos}How-To's}

doc/manpage_ocamlformat.mld

@@ -394,7 +394,7 @@ OPTIONS (CODE FORMATTING STYLE)
            multi-line-only.
 
        --parse-docstrings
-           Parse and format docstrings. The flag is unset by default.
+           Parse and format docstrings. The flag is set by default.
 
        --parse-toplevel-phrases
            Parse and format toplevel phrases and their output. The flag is

dune

@@ -19,7 +19,7 @@
 (rule
  (with-stdout-to
   dune-project.formatted
-  (run dune format-dune-file dune-project)))
+  (run dune format-dune-file %{dep:dune-project})))
 
 (rule
  (alias fmt)

dune-project

@@ -82,7 +82,6 @@
    (>= 1.4.0))
   ; for vendored odoc-parser
   astring
-  result
   camlp-streams))
 
 (package