Document the deprecation of @raises over @throws

misc_docs/syntax/decorator_does_not_raise.mdx

@@ -4,12 +4,15 @@ keywords: ["doesNotRaise", "decorator"]
 name: "@doesNotRaise"
 summary: "This is the `@doesNotRaise` decorator."
 category: "decorators"
+status: "deprecated"
 ---
 
-> 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).
+> Deprecated since v12.0.0. Use the [@doesNotThrow](/syntax-lookup#does-not-throw-decorator) decorator instead.
 
-`@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.
+> 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).
+
+`@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.
 
 ### References
 
-- [Reanalyze: Exception Analysis](https://github.com/rescript-lang/reanalyze/blob/master/EXCEPTION.md)
+- [Reanalyze: Exception Analysis](/docs/manual/v12.0.0/editor-plugins#exception-analysis)

misc_docs/syntax/decorator_does_not_throw.mdx

@@ -0,0 +1,15 @@
+---
+id: "does-not-throw-decorator"
+keywords: ["doesNotThrow", "decorator"]
+name: "@doesNotThrow"
+summary: "This is the `@doesNotThrow` decorator."
+category: "decorators"
+---
+
+> 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).
+
+`@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.
+
+### References
+
+- [Reanalyze: Exception Analysis](/docs/manual/v12.0.0/editor-plugins#exception-analysis)

misc_docs/syntax/decorator_raises.mdx

@@ -4,12 +4,15 @@ keywords: ["raises", "decorator"]
 name: "@raises"
 summary: "This is the `@raises` decorator."
 category: "decorators"
+status: "deprecated"
 ---
 
-> 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).
+> Deprecated since v12.0.0. Use the [@throws](/syntax-lookup#throws-decorator) decorator instead.
 
-`@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.
+> 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).
+
+`@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.
 
 ### References
 
-- [Reanalyze: Exception Analysis](https://github.com/rescript-lang/reanalyze/blob/master/EXCEPTION.md)
+- [Reanalyze: Exception Analysis](/docs/manual/v12.0.0/editor-plugins#exception-analysis)

misc_docs/syntax/decorator_throws.mdx

@@ -0,0 +1,15 @@
+---
+id: "throws-decorator"
+keywords: ["throws", "decorator"]
+name: "@throws"
+summary: "This is the `@throws` decorator."
+category: "decorators"
+---
+
+> 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).
+
+`@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.
+
+### References
+
+- [Reanalyze: Exception Analysis](/docs/manual/v12.0.0/editor-plugins#exception-analysis)

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

@@ -40,7 +40,89 @@ The code analysis provides extra checks for your ReScript project, such as detec
 ### Configuration
 
 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.  
-More details: [reanalyze config docs](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson)
+More details: [reanalyze config docs](https://github.com/rescript-associlangation/reanalyze#configuration-via-bsconfigjson)
+
+### Exception analysis
+
+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.
+Nested functions need to be annotated separately.
+
+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).
+
+Here's an example, where the analysis reports a warning any time an exception is thrown, and not caught:
+
+```rescript
+let throws = () => throw(Not_found)
+```
+
+reports:
+
+```sh
+
+  Exception Analysis
+  File "A.res", line 1, characters 4-10
+  throws might throw Not_found (A.res:1:19) and is not annotated with @throws(Not_found)
+```
+
+No warning is reported when a `@throws` annotation is added:
+
+```rescript
+@throws(Not_found)
+let throws = () => throw(Not_found)
+```
+
+When a function throws multiple exceptions, a tuple annotation is used:
+
+
+```rescript
+exception A
+exception B
+
+@throws([A, B])
+let twoExceptions = (x, y) => {
+  if (x) {
+    throw(A)
+  }
+  if (y) {
+    throw(B)
+  }
+}
+```
+
+It is possible to silence the analysis by adding a `@doesNotThrow` annotation:
+
+```rescript
+@throws(Invalid_argument)
+let stringMake1 = String.make(12, ' ')
+
+// Silence only the make function
+let stringMake2 = (@doesNotThrow String.make)(12, ' ')
+
+// Silence the entire call (including arguments to make)
+let stringMake3 = @doesNotThrow String.make(12, ' ')
+
+```
+
+#### Limitations
+
+- The libraries currently modeled are limited to `Array`, `Buffer`, `Bytes`, `Char`, `Filename`, `Hashtbl`, `List`, `Pervasives`, `Str`, `String` from the standard library, and `bs-json`, and `Json` from `Js`. Models are currently vendored in the analysis, and are easy to add (see [`src/ExnLib.ml`](src/ExnLib.ml))
+- Generic exceptions are not understood by the analysis. For example `exn` is not recognized below (only concrete exceptions are):
+
+```rescript
+try (foo()) { | exn => throw(exn) }
+```
+
+- Uses of e.g. `List.hd` 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.
+- There is no special support for functors. So with `Hashtbl.Make(...)` the builtin model will not apply. So the analysis won't report that the following can throw `Not_found`:
+
+```rescript
+module StringHash =
+  Hashtbl.Make({
+    include String
+    let hash = Hashtbl.hash
+  })
+let specializedHash = tbl => StringHash.find(tbl, "abc")
+```
 
 ### Guide