[FEATURE] Command to provide information for OCaml syntax

[PizieDust]

closes #1692

FEATURE: New Merlin Command - Syntax Document

Introduction

The Document command of Merlin returns comments written in code. This PR introduces a new command, the Syntax Document command which takes the syntax under the cursor, analyses it's TypedTree nodes and returns specific documentation for the Syntax.

Code Example

Code

type point = { x:int; y:int }

Output

{
   "name": "Record types",
   "description": "Allows you to define variants with a fixed set of fields, and all of the constructors for a record variant type must have the same fields",
   "url": "https://v2.ocaml.org/manual/extensiblevariants.html"
}

This command can also identify specific

Code

type point = private { x:int; y:int }

Output

{
   "name": "Private Record Types",
   "description": "Values of a record type declared private can be de-structured via the expr . field notation. However, values of these types cannot be constructed directly by record construction.",
   "url": "https://v2.ocaml.org/releases/5.1/htmlman/privatetypes.html#ss:private-types-variant"
}

Scope

This command for a start covers Language Extensions of OCaml. The covered sections include:

• Recursive definition of values
• Recursive modules
• Recovering the type of a module
• Signature Substitutions (Destructive substitutions, Local substitutions)
• Extensible Variant types
• Variant types
• Abstract types
• Record types
• Private types
• Empty variant types
• Locally abstract data types
• Bigarray access
• Type-level module aliases
• Overriding in open statements
• Generalized algebraic datatypes
• Attributes
• Generative functors
• Extension operators **
• Inline records ==== extensible variants
• Alerts
• Binding operators

More sections will be covered and updated to the command along with other parts of the OCaml programming language.

cc @voodoos @pitag-ha

[voodoos]

That's much better !

Now is probably a good time to decide which features we actually want to document.

There are two possibilities here:

• If the feature is aimed at complete beginner, it might make sense to document as much of the syntax as we can.
• Or we just want to shed a light on weird / rarely use OCaml features that might puzzle even seasoned developers.

@trefis, @pitag-ha, what's your feeling about this ?

It might also depend on how the feature is used: is it called on every on-hover in LSP ? Or only on specific code actions ?

[voodoos]

@PizieDust we discussed with trefis and Sonja and for the scope of the feature we think you can first focus on "language extensions". These are advanced features that were added to OCaml other the time and are often not well known by beginners.

You can find the list of these features here:
https://v2.ocaml.org/releases/5.1/htmlman/extn.html

About the UI, we can start (after the backend part in Merlin is done) by extending hover with the new information and then make it configurable. (And in fact, rework the hover command in general, it could be more useful than it is now in some situations).

[PizieDust]

Amazing. I should be moving this PR from draft soon

[voodoos]

I made a (very incomplete) round of review: could you reformat the file (I provided the result of ocamlformating it in a comment), and refactor / promote the result of the tests so that they can be used to understand the expected behavior ?

[pitag-ha]

This is super cool, @PizieDust , thanks a lot!

Are you planning to add an mli-file for syntax_doc.ml once you won't change that file that much anymore?

[voodoos]

Nice, you're making good progress on this :-)

I made a few comments, and you should also try to sort out the rebase mess :-)

[voodoos]

Right, I think we just need to improve the locally abstract data types case before merging a first version of this PR.

[voodoos]

I think the PR is almost ready.
I just made a few formatting remarks.

Do you want to rebase and squash your changes into meaningful commits ?
If not I can simply squash everything before merging.