Deprecate @raises in favor of @throws in reanalyze

[Copilot]

Overview

This PR deprecates the @raises decorator in reanalyze in favor of @throws to better align with JavaScript and ReScript terminology. The change maintains full backward compatibility while guiding users toward the new decorator.

Motivation

ReScript uses throw for raising exceptions (not raise), so using @throws for the exception analysis decorator provides better consistency with the language's terminology and makes it more intuitive for developers.

Changes

Core Reanalyze

• Exception.ml: Updated to accept both @throws/@throw (new) and @raises/@raise (deprecated) decorators
• Log_.ml: Updated warning messages to suggest @throws instead of @raises

Example warning message before:

myFunction might raise Not_found and is not annotated with @raises(Not_found)

Example warning message after:

myFunction might raise Not_found and is not annotated with @throws(Not_found)

IDE/Editor Support

• CompletionDecorators.ml: Added @throws decorator with full documentation and marked @raises as deprecated with a clear migration message

Documentation & Examples

• Updated all test files to use @throws decorator
• Updated expected test outputs to reflect new terminology
• Updated Stdlib_JSON runtime library to use @throws

Backward Compatibility

✅ No breaking changes. Existing code using @raises will continue to work without modification. The implementation accepts all variants:

// NEW - Recommended
@throws(MyException)
let myFunction = () => throw(MyException)

// OLD - Still works but deprecated
@raises(MyException)
let myFunction = () => throw(MyException)

IDE users will see a deprecation notice when using @raises, guiding them to use @throws instead, but their code will function identically.

Migration

Users can migrate at their own pace. Simply replace @raises with @throws:

-@raises(Not_found)
+@throws(Not_found)
 let findValue = key => Dict.getExn(myDict, key)

Both decorators accept the same syntax:

• Single exception: @throws(MyException)
• Multiple exceptions: @throws([E1, E2, E3])

Original prompt

deprecate the use of @raises in reanalyze and use @throws instead.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[pkg-pr-new]

Open in StackBlitz

rescript

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

@rescript/darwin-arm64

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

@rescript/darwin-x64

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

@rescript/linux-arm64

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

@rescript/linux-x64

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

@rescript/runtime

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

@rescript/win32-x64

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

commit: 501eaa2

[tsnobip]

fixes #7680.

[cknitt]

We should check the terminology - are there still any other places using "raise" instead of "throw"

[cknitt]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. You're on a roll.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

[cknitt]

LGTM.
Maybe @cristianoc would like to have a look, too?