Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document docstrings / doc headers in ReScript #158

Open
ryyppy opened this issue Jan 2, 2021 · 3 comments
Open

Document docstrings / doc headers in ReScript #158

ryyppy opened this issue Jan 2, 2021 · 3 comments

Comments

@ryyppy
Copy link
Member

ryyppy commented Jan 2, 2021

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)

@ryyppy ryyppy added the manual label Jan 2, 2021
@jfrolich
Copy link

jfrolich commented Jan 2, 2021

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.

@ryyppy ryyppy added this to the 2021 / January Release milestone Jan 3, 2021
@bobzhang
Copy link
Member

bobzhang commented Jan 4, 2021

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
Copy link
Member Author

ryyppy commented Jan 4, 2021

@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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

3 participants