Description
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)