What are the plans for documentation comments?

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?

2 Likes

Hello!

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

3 Likes

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?

1 Like

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

1 Like

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

2 Likes