You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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\`.`)
letgreeting= (lang: string, name: string): string=> {
letgreet=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`. */letgreeting= (lang: string, name: string): string=> {
letgreet=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)
The text was updated successfully, but these errors were encountered:
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 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
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.
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:
Upcoming spec (short description):
Our plan is to keep docstring logic minimalistic and easy to deal with (while being useful in editors, like vscode):
Here is a potential example on how it might look like:
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)
The text was updated successfully, but these errors were encountered: