Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit673f3da

Browse files
authored
Document the deprecation of@raises over@throws (#1117)
* Document the deprecation of@raises over@throwsFollowing the changes introduced byrescript-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
1 parenta452799 commit673f3da

File tree

5 files changed

+115
-7
lines changed

5 files changed

+115
-7
lines changed

‎misc_docs/syntax/decorator_does_not_raise.mdx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,15 @@ keywords: ["doesNotRaise", "decorator"]
44
name:"@doesNotRaise"
55
summary:"This is the `@doesNotRaise` decorator."
66
category:"decorators"
7+
status:"deprecated"
78
---
89

9-
>This decorator requires[`reanalyze`](https://github.com/rescript-lang/reanalyze), a code analysis tool for ReScript, to be installed.[Click here to read about how you get started with reanalyze.](https://github.com/rescript-lang/reanalyze).
10+
>Deprecated since v12.0.0. Use the[@doesNotThrow](/syntax-lookup#does-not-throw-decorator) decorator instead.
1011
11-
`@doesNotRaise` is used to override the reanalyze's exception analysis and state that an expression does not raise any exceptions, even though the analysis reports otherwise. This can happen for example in the case of array access where the analysis does not perform range checks but takes a conservative stance that any access could potentially raise.
12+
>This decorator requires[`reanalyze`](https://github.com/rescript-lang/reanalyze), a code analysis tool for ReScript, to be installed.[Click here to read about how you get started with reanalyze.](/docs/manual/v12.0.0/editor-plugins#code-analysis).
13+
14+
`@doesNotRaise` is used to override the reanalyze's exception analysis and state that an expression does not throw any exceptions, even though the analysis reports otherwise. This can happen for example in the case of array access where the analysis does not perform range checks but takes a conservative stance that any access could potentially throw.
1215

1316
###References
1417

15-
-[Reanalyze: Exception Analysis](https://github.com/rescript-lang/reanalyze/blob/master/EXCEPTION.md)
18+
-[Reanalyze: Exception Analysis](/docs/manual/v12.0.0/editor-plugins#exception-analysis)
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
id:"does-not-throw-decorator"
3+
keywords:["doesNotThrow", "decorator"]
4+
name:"@doesNotThrow"
5+
summary:"This is the `@doesNotThrow` decorator."
6+
category:"decorators"
7+
---
8+
9+
>This decorator requires[`reanalyze`](https://github.com/rescript-lang/reanalyze), a code analysis tool for ReScript, to be installed.[Click here to read about how you get started with reanalyze.](/docs/manual/v12.0.0/editor-plugins#code-analysis).
10+
11+
`@doesNotThrow` is used to override the reanalyze's exception analysis and state that an expression does not throw any exceptions, even though the analysis reports otherwise. This can happen for example in the case of array access where the analysis does not perform range checks but takes a conservative stance that any access could potentially throw.
12+
13+
###References
14+
15+
-[Reanalyze: Exception Analysis](/docs/manual/v12.0.0/editor-plugins#exception-analysis)

‎misc_docs/syntax/decorator_raises.mdx‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,15 @@ keywords: ["raises", "decorator"]
44
name:"@raises"
55
summary:"This is the `@raises` decorator."
66
category:"decorators"
7+
status:"deprecated"
78
---
89

9-
>This decorator requires[`reanalyze`](https://github.com/rescript-lang/reanalyze), a code analysis tool for ReScript, to be installed.[Click here to read about how you get started with reanalyze.](https://github.com/rescript-lang/reanalyze).
10+
>Deprecated since v12.0.0. Use the[@throws](/syntax-lookup#throws-decorator) decorator instead.
1011
11-
`@raises` is picked up by reanalyze's exception analysis, and acknowledges that a function can raise exceptions that are not caught, and suppresses a warning in that case. Callers of the functions are then subjected to the same rule. Example`@raises(Exn)` or`@raises([E1, E2, E3])` for multiple exceptions.
12+
>This decorator requires[`reanalyze`](https://github.com/rescript-lang/reanalyze), a code analysis tool for ReScript, to be installed.[Click here to read about how you get started with reanalyze.](/docs/manual/v12.0.0/editor-plugins#code-analysis).
13+
14+
`@raises` is picked up by reanalyze's exception analysis, and acknowledges that a function can throw exceptions that are not caught, and suppresses a warning in that case. Callers of the functions are then subjected to the same rule. Example`@raises(Exn)` or`@raises([E1, E2, E3])` for multiple exceptions.
1215

1316
###References
1417

15-
-[Reanalyze: Exception Analysis](https://github.com/rescript-lang/reanalyze/blob/master/EXCEPTION.md)
18+
-[Reanalyze: Exception Analysis](/docs/manual/v12.0.0/editor-plugins#exception-analysis)
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
id:"throws-decorator"
3+
keywords:["throws", "decorator"]
4+
name:"@throws"
5+
summary:"This is the `@throws` decorator."
6+
category:"decorators"
7+
---
8+
9+
>This decorator requires[`reanalyze`](https://github.com/rescript-lang/reanalyze), a code analysis tool for ReScript, to be installed.[Click here to read about how you get started with reanalyze.](/docs/manual/v12.0.0/editor-plugins#code-analysis).
10+
11+
`@throws` is picked up by reanalyze's exception analysis, and acknowledges that a function can throw exceptions that are not caught, and suppresses a warning in that case. Callers of the functions are then subjected to the same rule. Example`@throws(Exn)` or`@throws([E1, E2, E3])` for multiple exceptions.
12+
13+
###References
14+
15+
-[Reanalyze: Exception Analysis](/docs/manual/v12.0.0/editor-plugins#exception-analysis)

‎pages/docs/manual/v12.0.0/editor-plugins.mdx‎

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,79 @@ The code analysis provides extra checks for your ReScript project, such as detec
4040
###Configuration
4141

4242
Add a`reanalyze` section to your`rescript.json` to control what the analyzer checks or ignores. You’ll get autocomplete for config options in the editor.
43-
More details:[reanalyze config docs](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson)
43+
More details:[reanalyze config docs](https://github.com/rescript-associlangation/reanalyze#configuration-via-bsconfigjson)
44+
45+
###Exception analysis
46+
47+
The exception analysis is designed to keep track statically of the exceptions that might be thrown at runtime. It works by issuing warnings and recognizing annotations. Warnings are issued whenever an exception is thrown and not immediately caught. Annotations are used to push warnings from he local point where the exception is thrown, to the outside context: callers of the current function.
48+
Nested functions need to be annotated separately.
49+
50+
Instructions on how to run the exception analysis using the`-exception` and`-exception-cmt` command-line arguments, or how to add`"analysis": ["exception"]` in`rescript.json` are contained in the[reanalyze config docs](https://github.com/rescript-associlangation/reanalyze#configuration-via-bsconfigjson).
51+
52+
Here's an example, where the analysis reports a warning any time an exception is thrown, and not caught:
53+
54+
```rescript
55+
let throws = () => throw(Not_found)
56+
```
57+
58+
reports:
59+
60+
```sh
61+
62+
Exception Analysis
63+
File"A.res", line 1, characters 4-10
64+
throws might throw Not_found (A.res:1:19) and is not annotated with @throws(Not_found)
65+
```
66+
67+
No warning is reported when a`@throws` annotation is added:
68+
69+
```rescript
70+
@throws(Not_found)
71+
let throws = () => throw(Not_found)
72+
```
73+
74+
When a function throws multiple exceptions, a tuple annotation is used:
75+
76+
```rescript
77+
exception A
78+
exception B
79+
80+
@throws([A, B])
81+
let twoExceptions = (x, y) => {
82+
if (x) {
83+
throw(A)
84+
}
85+
if (y) {
86+
throw(B)
87+
}
88+
}
89+
```
90+
91+
It is possible to silence the analysis by adding a`@doesNotThrow` annotation:
92+
93+
```rescript
94+
@throws(Invalid_argument)
95+
let stringMake1 = String.make(12, ' ')
96+
97+
// Silence only the make function
98+
let stringMake2 = (@doesNotThrow String.make)(12, ' ')
99+
100+
// Silence the entire call (including arguments to make)
101+
let stringMake3 = @doesNotThrow String.make(12, ' ')
102+
103+
```
104+
105+
####Limitations
106+
107+
- The libraries currently modeled are limited to the standard library, Belt and Js modules. Models are currently vendored in the analysis, and are easy to add (see[`analysis/reanalyze/src/ExnLib.ml`](https://github.com/rescript-lang/rescript/blob/master/analysis/reanalyze/src/ExnLib.ml))
108+
- Generic exceptions are not understood by the analysis. For example`exn` is not recognized below (only concrete exceptions are):
109+
110+
```rescript
111+
try (foo()) { | exn => throw(exn) }
112+
```
113+
114+
- Uses of e.g.`List.head` are interpreted as belonging to the standard library. If you re-define`List` in the local scope, the analysis it will think it's dealing with`List` from the standard library.
115+
- There is no special support for module functions.
44116

45117
###Guide
46118

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp