You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* 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
> 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.
10
11
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.
> 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.
> 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.
10
11
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.
> 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.
Copy file name to clipboardExpand all lines: pages/docs/manual/v12.0.0/editor-plugins.mdx
+73-1Lines changed: 73 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -40,7 +40,79 @@ The code analysis provides extra checks for your ReScript project, such as detec
40
40
### Configuration
41
41
42
42
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.
0 commit comments