`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