Document docstrings / doc headers in ReScript

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)

Start by reviewing the current documentation for ReScript docstrings and the issue's proposed syntax. Document the current @ocaml.doc approach, the decision not to use ocamldoc string format, and the proposed markdown-based doc headers; done means the temporary guidance clearly records the current situation and pending specification.