Add option to force build before extracting doc

[shulhi]

Fix #8040

The rescript-tools doc extracts the docs from cmt files. cmt files require the source code to be rebuilt to refresh them. This adds an option to run the build before extracting the doc so the cmt files are always up to date.

@nojaf @cknitt I'm not sure if this something we want, but I feel this is helpful (or less misleading to the users). Users would expect running the tools will always work without rebuilding.

Another thing to consider is the change in the output when the flag is provided.

 rescript-demo main*​
 ❯ npx rescript-tools doc src/Demo.res --build
[1/3] 🧹 Cleaned 0/1 in 0.00s
[2/3] 🧱 Parsed 1 source files in 0.01s
[3/3] 🤺 Compiled 1 modules in 0.01s

✨ Finished Compilation in 0.02s

{
  "name": "Demo",
  "docstrings": [],
  "source": {
    "filepath": "src/Demo.res",
    "line": 1,
    "col": 1
  },
  "items": [
  {
    "id": "Demo.x",
    "kind": "value",
    "name": "x",
    "signature": "let x: int",
    "docstrings": ["Hello world!!!"],
    "source": {
      "filepath": "src/Demo.res",
      "line": 4,
      "col": 5
    },
    "detail":
    {
      "kind": "signature",
      "details": {
      "returnType": {
        "path": "int"
      }
    }
    }
  }]
}

If the downstream expects a proper JSON, this will break any downstream CLI tools that depends on this.

Marked this as draft as this needs a bit more polishing.

[pkg-pr-new]

Open in StackBlitz

rescript

npm i https://pkg.pr.new/rescript-lang/rescript@8119

@rescript/darwin-arm64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/darwin-arm64@8119

@rescript/darwin-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/darwin-x64@8119

@rescript/linux-arm64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/linux-arm64@8119

@rescript/linux-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/linux-x64@8119

@rescript/runtime

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/runtime@8119

@rescript/win32-x64

npm i https://pkg.pr.new/rescript-lang/rescript/@rescript/win32-x64@8119

commit: b6e08f2

[nojaf]

If the downstream expects a proper JSON, this will break any downstream CLI tools that depends on this.

This is quite unusable.

I'm also not convinced we should fix this in a patched up way.
Would take a step back and consider making cmt recompute when doc strings changed instead.

[shulhi]

I'm also not convinced we should fix this in a patched up way. Would take a step back and consider making cmt recompute when doc strings changed instead.

I would agree on that, but the tools read from cmt which requires rebuild anyways to update them (i.e. cmt recompute when we run the build). The doc extraction reads from existing cmt.

[nojaf]

Actually, I take that back, cmt does change for me when I add doc comment.
Running rescript watch in one terminal, and rescript-tools doc in another did work for me.

Are we 100% sure this is not a user issue?

[shulhi]

Actually, I take that back, cmt does change for me when I add doc comment. Running rescript watch in one terminal, and rescript-tools doc in another did work for me.

Are we 100% sure this is not a user issue?

Let me rephrase this better. It changed because you have rescript watch running. The issue is rescript-tools doc expects users to rebuild the project whenever there are changes to get latest docs because it depends on cmt files. (cmt files only changed when we rebuild). So, changing doc comment and solely running rescript-tools doc will still give you outdated output because while the source code changed, the cmt files don't.

Unless this is the intended design, we still want to provide a solution because it can be confusing. Either through documentation or fixing how rescript-tools work.