rescript-lang / rescript-lang/rescript

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

Open
#8,040 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
OCaml
Stars
7.5k
Forks
485
Avg merge
1d 2h
Merged PRs (30d)
55

Description

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)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the rescript-tools doc command and reproduce the behavior using src/Demo.res from the issue. Trace how the command handles type definitions and /** */ comments, then run npx rescript-tools doc src/Demo.res again. Done means the output includes the type's docstring and a populated items array.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js
Domain
cli, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.