Add documentation

- add changelog entry
- add PROTOCOL documentation
- add vim doc

CHANGES.md

@@ -9,6 +9,14 @@ git version
     - fix location of module definitions done via functors (#1329, fixes #1199)
     - fix -cmt-path dirs mistakenly added to build path (#1330)
     - add new module holes that can replace module expressions (#1333)
+    - add a new command `construct` that builds a list of possible terms when
+      called on a typed hole (#1318)
+  + editor modes
+    - vim: add a simple interface to the new `construct` command:
+      `MerlinConstruct`. When several results are suggested, `<c-i>` and `<c-u>`
+      to show more or less deep results. (#1318)
+  + test suite
+    - cover the new `construct` command (#1318)
 
 merlin 4.2
 ==========

doc/dev/PROTOCOL.md

@@ -223,6 +223,17 @@ Entries is the list of possible completion. Each entry is made of:
 - a description, most of the time a type or a definition line, to be put next to the name in completion box
 - optional information which might not fit in the completion box, like signatures for modules or documentation string.
 
+### `construct -position <position> [ -with-values <none|local> -depth <int> ]`
+
+    -position <position>      Position where construct should happen
+    -with-values <none|local> Use values from the environment (defaults to none)
+    -depth <int>              Depth of the search (defaults to 1)
+
+When the position determined by `-position` is a hole (`_`), this command
+  returns a list of possible terms that could replace it given its type.
+When `-with-values` is set to local, values in the current environment will be
+  used in the constructed terms.
+
 ### `document -position <position> [ -identifier <string> ]`
 
     -position <position>  Position to complete
@@ -296,6 +307,11 @@ Returns all known findlib packages as a list of string.
 
 Returns supported compiler flags.The purpose of this command is to implement interactive completion of compiler settings in an IDE.
 
+### `holes`
+
+This command will return the ordered list of the positions and types of all
+holes in the current document.
+
 ### `jump -target <string> -position <position>`
 
         -target <string>  Entity to jump to

vim/merlin/doc/merlin.txt

@@ -111,6 +111,13 @@ Add these bindings to rename interactively: >
 
 See https://ocaml.github.io/merlin/destruct.ogv
 
+:MerlinConstruct                                            *:MerlinConstruct*
+
+When called from a hole "_", attempts to construct terms matching the hole's
+type. If only one result is found the hole is replaced immediately. If multiple
+results are found a list will appear. It is possible to ask for more or less
+deep results in that list using the shortcuts  "<c-i>" and "<c-u>".
+
 :MerlinOutline                                                *:MerlinOutline*
 
 Gives an "outline" of the current buffer, i.e. lists all the "definitions"
@@ -121,6 +128,16 @@ definition.
 The rendering (and interactivity) is provided by
 [ctrl-p](https://github.com/ctrlpvim/ctrlp.vim).
 
+:MerlinNextHole                                              *:MerlinNextHole*
+
+Moves the cursor forward to the closest hole "_". If there is no hole after the
+cursor the search will restart at the beginning of the buffer.
+
+:MerlinPreviousHole                                      *:MerlinPreviousHole*
+
+Moves the cursor backwards to the closest hole "_". If there is no hole before
+the cursor the search will restart at the end of the buffer.
+
 :MerlinILocate                                                *:MerlinILocate*
 
 This is an interactive version of |:MerlinLocate|, which relies on