From 93c52df46abc6f2207e70925944dabeaa88d03ff Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Mon, 16 May 2022 08:36:46 +0200 Subject: [PATCH 1/2] add @live and @dead attributes to syntax lookup --- misc_docs/syntax/decorator_dead.mdx | 15 +++++++++++++++ misc_docs/syntax/decorator_live.mdx | 16 ++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 misc_docs/syntax/decorator_dead.mdx create mode 100644 misc_docs/syntax/decorator_live.mdx diff --git a/misc_docs/syntax/decorator_dead.mdx b/misc_docs/syntax/decorator_dead.mdx new file mode 100644 index 000000000..0c9e7ba6b --- /dev/null +++ b/misc_docs/syntax/decorator_dead.mdx @@ -0,0 +1,15 @@ +--- +id: "dead-decorator" +keywords: ["dead", "decorator"] +name: "@dead" +summary: "This is the `@dead` decorator." +category: "decorators" +--- + +The `@dead` decorator is for [`reanalyze`](https://github.com/rescript-association/reanalyze), a static analysis tool for ReScript that can do dead code analysis. + +`@dead` suppresses reporting on the value/type, but can also be used to force the analysis to consider a value as dead. Typically used to acknowledge cases of dead code you are not planning to address right now, but can be searched easily later. + +### References + +- [Reanalyze: Controlling reports with Annotations](https://github.com/rescript-association/reanalyze#dce-controlling-reports-with-annotations) diff --git a/misc_docs/syntax/decorator_live.mdx b/misc_docs/syntax/decorator_live.mdx new file mode 100644 index 000000000..d9b53a5e8 --- /dev/null +++ b/misc_docs/syntax/decorator_live.mdx @@ -0,0 +1,16 @@ +--- +id: "live-decorator" +keywords: ["live", "decorator"] +name: "@live" +summary: "This is the `@live` decorator." +category: "decorators" +--- + +The `@live` decorator is for [`reanalyze`](https://github.com/rescript-association/reanalyze), a static analysis tool for ReScript that can do dead code analysis. + +`@live` tells the dead code analysis that the value should be considered live, even though it might appear to be dead. This is typically used in case of FFI where there are indirect ways to access values. +It can be added to everything that could otherwise be considered unused by the dead code analysis - values, functions, arguments, records, individual record fields, and so on. + +### References + +- [Reanalyze: Controlling reports with Annotations](https://github.com/rescript-association/reanalyze#dce-controlling-reports-with-annotations) From bbfda347cdd7136ca21a5e3cd0f86b92d3392d7e Mon Sep 17 00:00:00 2001 From: Gabriel Nordeborn Date: Sat, 28 May 2022 21:22:12 +0200 Subject: [PATCH 2/2] add @raises + @doesNotRaise docs, + add info boxes about decorators being for reanalyze --- misc_docs/syntax/decorator_dead.mdx | 4 ++-- misc_docs/syntax/decorator_does_not_raise.mdx | 15 +++++++++++++++ misc_docs/syntax/decorator_live.mdx | 4 ++-- misc_docs/syntax/decorator_raises.mdx | 15 +++++++++++++++ 4 files changed, 34 insertions(+), 4 deletions(-) create mode 100644 misc_docs/syntax/decorator_does_not_raise.mdx create mode 100644 misc_docs/syntax/decorator_raises.mdx diff --git a/misc_docs/syntax/decorator_dead.mdx b/misc_docs/syntax/decorator_dead.mdx index 0c9e7ba6b..a8e55beae 100644 --- a/misc_docs/syntax/decorator_dead.mdx +++ b/misc_docs/syntax/decorator_dead.mdx @@ -6,9 +6,9 @@ summary: "This is the `@dead` decorator." category: "decorators" --- -The `@dead` decorator is for [`reanalyze`](https://github.com/rescript-association/reanalyze), a static analysis tool for ReScript that can do dead code analysis. +> This decorator requires [`reanalyze`](https://github.com/rescript-association/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-association/reanalyze). -`@dead` suppresses reporting on the value/type, but can also be used to force the analysis to consider a value as dead. Typically used to acknowledge cases of dead code you are not planning to address right now, but can be searched easily later. +`@dead` is picked up by reanalyze's dead code analysis, and suppresses reporting on the value/type, but can also be used to force the analysis to consider a value as dead. Typically used to acknowledge cases of dead code you are not planning to address right now, but can be searched easily later. ### References diff --git a/misc_docs/syntax/decorator_does_not_raise.mdx b/misc_docs/syntax/decorator_does_not_raise.mdx new file mode 100644 index 000000000..76ce55b1b --- /dev/null +++ b/misc_docs/syntax/decorator_does_not_raise.mdx @@ -0,0 +1,15 @@ +--- +id: "does-not-raise-decorator" +keywords: ["doesNotRaise", "decorator"] +name: "@doesNotRaise" +summary: "This is the `@doesNotRaise` decorator." +category: "decorators" +--- + +> This decorator requires [`reanalyze`](https://github.com/rescript-association/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-association/reanalyze). + +`@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. + +### References + +- [Reanalyze: Exception Analysis](https://github.com/rescript-association/reanalyze/blob/master/EXCEPTION.md) diff --git a/misc_docs/syntax/decorator_live.mdx b/misc_docs/syntax/decorator_live.mdx index d9b53a5e8..9eb7cbc28 100644 --- a/misc_docs/syntax/decorator_live.mdx +++ b/misc_docs/syntax/decorator_live.mdx @@ -6,9 +6,9 @@ summary: "This is the `@live` decorator." category: "decorators" --- -The `@live` decorator is for [`reanalyze`](https://github.com/rescript-association/reanalyze), a static analysis tool for ReScript that can do dead code analysis. +> This decorator requires [`reanalyze`](https://github.com/rescript-association/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-association/reanalyze). -`@live` tells the dead code analysis that the value should be considered live, even though it might appear to be dead. This is typically used in case of FFI where there are indirect ways to access values. +`@live` tells reanalyze's dead code analysis that the value should be considered live, even though it might appear to be dead. This is typically used in case of FFI where there are indirect ways to access values. It can be added to everything that could otherwise be considered unused by the dead code analysis - values, functions, arguments, records, individual record fields, and so on. ### References diff --git a/misc_docs/syntax/decorator_raises.mdx b/misc_docs/syntax/decorator_raises.mdx new file mode 100644 index 000000000..f752f198f --- /dev/null +++ b/misc_docs/syntax/decorator_raises.mdx @@ -0,0 +1,15 @@ +--- +id: "raises-decorator" +keywords: ["raises", "decorator"] +name: "@raises" +summary: "This is the `@raises` decorator." +category: "decorators" +--- + +> This decorator requires [`reanalyze`](https://github.com/rescript-association/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-association/reanalyze). + +`@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. + +### References + +- [Reanalyze: Exception Analysis](https://github.com/rescript-association/reanalyze/blob/master/EXCEPTION.md)