Document docstrings / doc headers in ReScript

[ryyppy]

This issue was created to clarify the situation regarding ReScript docstrings. It's probably worth creating a temporary doc explaining the situation until the final spec for handling docstrings is implemented.

tldr; We won't use the ocamldoc string format

Right now in ReScript, we don't implement any special comment attaching behavior (not a big deal, it's mostly about spec'ing out how users should document ReScript code), so we still rely on using @ocaml.doc decorators.

Example:

@ocaml.doc(`
\`greeting(lang, name)\` Returns a greeting string for given \`name\` in language \`lang\`.
`)
let greeting = (lang: string, name: string): string => {
    let greet = switch(lang) {
       | "de" => "Hallo "
       | "en"
       | _ => "Hello "
    }
    greet ++ name
}

Upcoming spec (short description):

Our plan is to keep docstring logic minimalistic and easy to deal with (while being useful in editors, like vscode):

• Content should be written in markdown flavoured markdown
• We will not introduce any new syntax (kinda like the go approach, that also just uses plain text essentially)
• For cross referencing, we will take some inspiration from ocamldoc (for how to design hrefs) and use markdown hyperlink syntax
• For the initial function example, we will just use backticks (`)
• Doc headers need to be before a function / value definition (in contrary to ocamldoc's "before or after" behavior)

Here is a potential example on how it might look like:

/** `greeting(lang, name)` Returns a greeting string for given `name` in language `lang`. */
let greeting = (lang: string, name: string): string => {
    let greet = switch(lang) {
       | "de" => "Hallo "
       | "en"
       | _ => "Hello "
    }
    greet ++ name
}

There will be more cases to consider, such as where to put comment strings for variants etc, but this will be part of a more thorough spec (\cc @IwanKaramazow for syntax related comments)

[jfrolich]

ocaml-community/omd#215 see this PR on how to convert markdown to ocamldoc. Might be helpful. Almost all features map pretty nicely including cross referencing.

[bobzhang]

Is there any difference between ocaml.doc and doc, if so, shall we go with doc?

@doc(`
\`greeting(lang, name)\` Returns a greeting string for given \`name\` in language \`lang\`.
`)

Any way to reduce the usage of \ here, it is a bit too much backslash here

[ryyppy]

@bobzhang Currently, rescript-editor-support uses the old reason-lsp logic which relies on a vendored version of odoc, and I think odoc looks for @ocaml.doc decorators to extract the content (I think this is what @cristianoc was referring to lately?).

I discussed with @IwanKaramazow to re-introduce the old Reason functionality of using /** */ block comment syntax, but we need to draft out a proposal on how the different language constructs should be annotated.

e.g. how should the parser treat comments attached to variant constructors (to allow doc generation for each variant).

So ultimately, this @ocaml.doc(\`)` syntax shouldn't be exposed to the user in the end