Separate module and expression deprecated decorators

Author: kevanstannard

misc_docs/syntax/decorator_deprecated.mdx

@@ -0,0 +1,47 @@
+---
+id: "scope-deprecated-decorator"
+keywords: ["deprecated", "decorator"]
+name: "@deprecated"
+summary: "This is the `expression deprecation` decorator."
+category: "decorators"
+---
+
+The `@deprecated` decorator is used to annotate deprecated types, values and modules within a file. This may be used by ReScript tooling to highlight deprecated code during development.
+
+See the `@@deprecated` decorator to deprecate whole file modules.
+
+### Examples
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+@deprecated
+type person = {id: int, name: string}
+
+@deprecated
+let customDouble = n => n * 2
+
+@deprecated("Use OtherModule.customTriple instead")
+let customTriple = n => n * 3
+
+@deprecated("Use OtherModule instead")
+module MyModule = {
+  type t
+}
+```
+
+```js
+function customDouble(n) {
+  return n << 1;
+}
+
+function customTriple(n) {
+  return Math.imul(n, 3);
+}
+
+var MyModule = {};
+```
+
+</CodeTab>
+
+

misc_docs/syntax/decorator_expression_deprecated.mdx

@@ -0,0 +1,30 @@
+---
+id: "module-deprecated-decorator"
+keywords: ["deprecated", "decorator"]
+name: "@@deprecated"
+summary: "This is the `module deprecation` decorator."
+category: "decorators"
+---
+
+The `@@deprecated` decorator is used to indicate that a whole module is deprecated. This may be used by ReScript tooling to highlight deprecated code during development.
+
+See the `@deprecated` decorator to deprecate expressions.
+
+### Examples
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res
+// Indicate whole module is deprecated
+@@deprecated
+
+// Indicate whole module is deprecated, with a comment
+@@deprecated("Use OtherModule instead")
+```
+
+```js
+```
+
+</CodeTab>
+
+