`rescript-tools doc` not extracting docstrings from type definitions

[nathan-tranquilla]

Environment

• ReScript version: 12.0.0
• OS: macOS
• Node version: v22.20.0

Problem

The rescript-tools doc command is not extracting docstrings from type definitions and returns an empty items array, even when using proper /** */ documentation comment syntax.

Minimal Reproducible Example

File: src/Demo.res

/**
 * Test
 */
type t = {
  name: string,
  servings: int,
}

Command

npx rescript-tools doc src/Demo.res

Output

{
  "name": "Demo",
  "docstrings": [],
  "source": {
    "filepath": "src/Demo.res",
    "line": 1,
    "col": 1
  },
  "items": []
}

Steps to Reproduce

• Create a new ReScript project
• Create Demo.res with the content above
• Run npx rescript-tools doc src/Demo.res
• Observe empty items array and missing docstrings

Additional Context

This affects tooling that depends on rescript-tools for documentation extraction (such as codegen)

[nathan-tranquilla]

Further details. I've noted what appears to be some internal caching. Unless the record has changed, it appears changes to the docstring will not show.

[nojaf]

The information for this is coming from the *.cmt file of Demo.res.
If that didn't change the doc command won't yield anything new.
So, change code, recompile, rerun doc command, should trigger a change.

[nathan-tranquilla]

This appears to have resolved the issue. However, if only the docstring changes (as in my case), the tool continues to output the same json.

[nojaf]

Hmm, that is not my experience. You are running the compiler in watch mode right?

• One terminal in watch mode,
• Another terminal where you test doc command, update file, test doc command again

[shulhi]

• One terminal in watch mode,
• Another terminal where you test doc command, update file, test doc command again

This requires the code to be built again (so the cmt file actually changed). Changing the comment, and rerunning the rescript-ool doc won't work without rebuilding. Should we force rebuild or add an option to force build? I'm leaning towards adding an option to force rebuild.