What are the plans for documentation comments?

1

I’m wondering what the plan for API documentation in resi files is.

If I understand correctly, the current state seems to be:

  • /** ... */ comments are not converted to @ocaml.text and @ocaml.doc annotations
  • bs-platform doesn’t include odoc
  • bsb doesn’t call odoc
  • odoc has no --syntax=res.

Is the plan to support an odoc-based workflow for API documentation?

5 Likes
2

Hello!

No plan to support odoc. it’s a bit too much. But we’re likely open to support similar feature.

5 Likes
3

When converting from reason syntax to ReScript, I noticed many new ppx annotations in place of normal block comments like this:


@ocaml.doc("
 * previously just a /** comment */
 ")

Is there something nice I can already (easily) do with this? Like doc generation? How do people use those in general?

2 Likes
4

I think these strings show in the signature hints in VS Code. Other than that, we don’t generate docs for our frontend code, we rather use Storybook for components, but that means no HTML docs for non-visual modules, so working odoc generation would be nice. I guess it would be even nicer for teams using ReScript for everything (we use native OCaml for our backend).

2 Likes
5

Doc comments don’t get any special treatment atm. There are plans to implement a nicer version, this might be Q2 2021 or later.

3 Likes
6

Are you all writing the the @ocaml.doc tags by hand then?

@ocaml.doc(
  "update the url with the string path. Example: `push(\"/book/1\")`, `push(\"/books#title\")` "
)

Is there some short cut you are aware of?

Thanks.

1 Like
7

No shortcut yet. Dedicated doc header parsing will be added later on, so just go on with ocaml.doc for now. The reformatter will take care of the annotations as soon as we have the /** */ syntax.

4 Likes
8

Can I somehow learn more about the plans for documentation comments? This is maybe the main blocker stopping us from switching to rescript syntax, and I would like to understand whether you’re moving (or at least thinking) into a direction that would work for us.

FYI, as minimum support, I think we would need:

  • vs code lets us write doc comments in resi files
  • vs code shows doc comments from resi files in res files when hovering over an imported name
  • vs code shows doc comments from resi files in res files when selecting a name to autocomplete

Also helpful would be:

  • vs code lets us write doc comments in res files
  • vs code shows doc comments from the same res file when hovering over a local name
  • vs code shows doc comments from the same res file when selecting a name to autocomplete
  • generation of a website with API documentation from a resi file, resolving all includes, with custom ordering and some interspersed text

Absolutely amazing would be:

  • Documentation for module types can declare documentation arguments with defaults that can be overwritten when including a module type (a bit like in Scaladoc, but actually working in a sane way)

edit: Oh I just saw in the release notes for rescript-vscode 1.1.1 that hover is supposed to show documentation. Maybe I’m doing something wrong in my testing. Will try harder.

another edit: Ok I see now that with res&resi only, @ocaml.doc("...") comments work in VS code as expected :smile: :+1: Interop with re&rei seems a bit sketchy but I guess we can live with that. Overall the VS Code plugin appears pretty nice. Maybe it is time for us to switch now :thinking:

1 Like
9

The @ocaml.doc format is a placeholder, which will later be replaced by first-class doc comments in the language. However, changing over will probably be automatic by reformatting once or something.

3 Likes