Deprecate @raises in favor of @throws in reanalyze by Copilot · Pull Request #7932 · rescript-lang/rescript

Copilot · 2025-10-02T09:29:24Z

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.

@throws

- Update reanalyze Exception.ml to accept both @throws and @raises decorators - Update warning messages to use @throws terminology - Add @throws decorator to completion with documentation - Mark @raises as deprecated in completion - Update all test files to use @throws instead of @raises - Update expected test outputs to reflect @throws terminology - Update Stdlib_JSON to use @throws instead of @raises Co-authored-by: tsnobip <2479216+tsnobip@users.noreply.github.com>

pkg-pr-new · 2025-10-02T10:15:45Z

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 · 2025-10-02T10:50:18Z

fixes #7680.

cknitt

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

cknitt · 2025-10-03T06:42:40Z

@codex review

chatgpt-codex-connector · 2025-10-03T06:46:22Z

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 👍.

Following the changes introduced by rescript-lang/rescript#7932

cknitt

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

@raises

* Document the deprecation of @raises over @throws Following the changes introduced by rescript-lang/rescript#7932 * document exception analysis in editor-plugins * format * update libraries set up to use exception analysis * remove the outdated functor example for exception analysis * rename List.hd to List.head (its name in Stdlib) * rename functors to module functions

@raises

* Initial plan * Deprecate @raises in favor of @throws in reanalyze - Update reanalyze Exception.ml to accept both @throws and @raises decorators - Update warning messages to use @throws terminology - Add @throws decorator to completion with documentation - Mark @raises as deprecated in completion - Update all test files to use @throws instead of @raises - Update expected test outputs to reflect @throws terminology - Update Stdlib_JSON to use @throws instead of @raises Co-authored-by: tsnobip <2479216+tsnobip@users.noreply.github.com> * replace other references of `raise` with `throw` * update "Contribute to the API Reference" * update changelog * update docs some more * rename some more raises * rename raise to throw in API docs * remove unused @throws annotations * update completion --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: tsnobip <2479216+tsnobip@users.noreply.github.com> Co-authored-by: tsnobip <dontshootthink@gmail.com> Signed-off-by: Pedro Castro <aspeddro@gmail.com>

@raises

Why: 12.0.0-beta.14 deprecated `@raises` and `@doesNotRaise` in favour of `@throws` and `@doesNotThrow` (#7932). v13 drops the old spellings, the undeprecated `@throw` synonym, and the `@doNotThrow`/case variants, so one spelling remains for each annotation. An old spelling is now an unknown attribute, so the code it annotated is reported like unannotated code. The compiler's own `[@doesNotRaise]` and `[@@raises]` annotations become `[@doesNotThrow]` and `[@@throws]`. Reanalyze modified (old annotation spellings): Example: @raises(Not_found) let oldRaisesAnnotation = () => throw(Not_found) Before (reanalyze): no issue After (reanalyze): Exception Analysis ExnOldSpellings.res:5:5-23 oldRaisesAnnotation might throw Not_found (ExnOldSpellings.res:5:32) and is not annotated with @throws(Not_found) Review: Why no dedicated warning for an old spelling? The missing-annotation report already names the `@throws(...)` to write, and recognizing the old names only to reject them would keep them in the analysis. Breaking: `@raises`, `@raise`, `@throw`, `@doesNotRaise`, `@doNotRaise`, `@doNotThrow` and the lower-case variants are ignored; write `@throws` and `@doesNotThrow`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Kbf3gGhHjzBTXqSo8Dckpb Signed-off-by: Christoph Knittel <ck@cca.io>

@raises

Why: 12.0.0-beta.14 deprecated `@raises` and `@doesNotRaise` in favour of `@throws` and `@doesNotThrow` (#7932). v13 drops the old spellings, the undeprecated `@throw` synonym, and the `@doNotThrow`/case variants, so one spelling remains for each annotation. An old spelling is now an unknown attribute, so the code it annotated is reported like unannotated code. The compiler's own `[@doesNotRaise]` and `[@@raises]` annotations become `[@doesNotThrow]` and `[@@throws]`. Reanalyze modified (old annotation spellings): Example: @raises(Not_found) let oldRaisesAnnotation = () => throw(Not_found) Before (reanalyze): no issue After (reanalyze): Exception Analysis ExnOldSpellings.res:5:5-23 oldRaisesAnnotation might throw Not_found (ExnOldSpellings.res:5:32) and is not annotated with @throws(Not_found) Review: Why no dedicated warning for an old spelling? The missing-annotation report already names the `@throws(...)` to write, and recognizing the old names only to reject them would keep them in the analysis. Breaking: `@raises`, `@raise`, `@throw`, `@doesNotRaise`, `@doNotRaise`, `@doNotThrow` and the lower-case variants are ignored; write `@throws` and `@doesNotThrow`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Kbf3gGhHjzBTXqSo8Dckpb Signed-off-by: Christoph Knittel <ck@cca.io>

Initial plan

f86a868

Copilot AI assigned Copilot and tsnobip Oct 2, 2025

Copilot started work on behalf of tsnobip October 2, 2025 09:29

View session

Copilot AI changed the title ~~[WIP] deprecate the use of @raises in reanalyze and use @throws instead.~~ Deprecate @raises in favor of @throws in reanalyze Oct 2, 2025

Copilot AI requested a review from tsnobip October 2, 2025 09:45

Copilot finished work on behalf of tsnobip October 2, 2025 09:45

tsnobip added 3 commits October 2, 2025 12:26

replace other references of raise with throw

8c82f5d

update "Contribute to the API Reference"

7276ad9

update changelog

30d09c9

tsnobip marked this pull request as ready for review October 2, 2025 10:49

update docs some more

9cce9fe

tsnobip requested a review from cknitt October 2, 2025 10:59

cknitt reviewed Oct 3, 2025

View reviewed changes

Comment thread analysis/reanalyze/src/Exception.ml Resolved

Comment thread analysis/reanalyze/src/Exception.ml Resolved

rename some more raises

9acd533

cknitt reviewed Oct 3, 2025

View reviewed changes

Comment thread packages/@rescript/runtime/Stdlib_JSON.res Resolved

cknitt requested a review from cristianoc October 3, 2025 07:08

rename raise to throw in API docs

4f5313a

tsnobip force-pushed the copilot/fix-ffd931b9-0aba-4a57-b568-72a4365d3180 branch from 2dc9cc9 to 4f5313a Compare October 3, 2025 07:16

remove unused @throws annotations

09d44ee

tsnobip requested a review from cknitt October 3, 2025 07:52

update completion

501eaa2

tsnobip force-pushed the copilot/fix-ffd931b9-0aba-4a57-b568-72a4365d3180 branch from 01d9c83 to 501eaa2 Compare October 3, 2025 07:57

tsnobip added a commit to rescript-lang/rescript-lang.org that referenced this pull request Oct 3, 2025

Document the deprecation of @raises over @throws

27e2a40

Following the changes introduced by rescript-lang/rescript#7932

tsnobip mentioned this pull request Oct 3, 2025

Document the deprecation of @raises over @throws rescript-lang/rescript-lang.org#1117

Merged

cknitt approved these changes Oct 3, 2025

View reviewed changes

tsnobip merged commit 11cde90 into master Oct 3, 2025
25 checks passed

tsnobip deleted the copilot/fix-ffd931b9-0aba-4a57-b568-72a4365d3180 branch October 3, 2025 13:25

cknitt mentioned this pull request Oct 19, 2026

[reanalyze] rename @raises to @throws #7680

Closed

cknitt mentioned this pull request Nov 3, 2026

Accept only @throws and @doesNotThrow in reanalyze #9210

Open

Navigation Menu

Repository navigation

Deprecate @raises in favor of @throws in reanalyze - #7932

Deprecate @raises in favor of @throws in reanalyze#7932
tsnobip merged 10 commits into
masterfrom
copilot/fix-ffd931b9-0aba-4a57-b568-72a4365d3180

Copilot AI commented Oct 2, 2025 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Oct 2, 2025 •

edited

Loading

Uh oh!

tsnobip commented Oct 2, 2025

Uh oh!

cknitt left a comment

Uh oh!

Uh oh!

Uh oh!

cknitt commented Oct 3, 2025

Uh oh!

chatgpt-codex-connector Bot commented Oct 3, 2025

Uh oh!

Uh oh!

cknitt left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Motivation

Changes

Core Reanalyze

IDE/Editor Support

Documentation & Examples

Backward Compatibility

Migration

Uh oh!

pkg-pr-new Bot commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tsnobip commented Oct 2, 2025

Uh oh!

cknitt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cknitt commented Oct 3, 2025

Uh oh!

chatgpt-codex-connector Bot commented Oct 3, 2025

Uh oh!

Uh oh!

cknitt left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Oct 2, 2025 •

edited

Loading

pkg-pr-new Bot commented Oct 2, 2025 •

edited

Loading