From 3ebdd5b5f549ba48dd1d38b01719a7ae073e3287 Mon Sep 17 00:00:00 2001
From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com>
Date: Thu, 3 Dec 2020 00:43:32 -0800
Subject: [PATCH] Add docs for `@decorator`

---
 _data/navigation.yaml   |  2 ++
 pages/tags/decorator.md | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+)
 create mode 100644 pages/tags/decorator.md

diff --git a/_data/navigation.yaml b/_data/navigation.yaml
index 72f8567..0717134 100644
--- a/_data/navigation.yaml
+++ b/_data/navigation.yaml
@@ -51,6 +51,8 @@ docs_nav:
         url: /pages/tags/alpha
       - title: '@beta'
         url: /pages/tags/beta
+      - title: '@decorator'
+        url: /pages/tags/decorator
       - title: '@deprecated'
         url: /pages/tags/deprecated
       - title: '@defaultValue'
diff --git a/pages/tags/decorator.md b/pages/tags/decorator.md
new file mode 100644
index 0000000..bbb668f
--- /dev/null
+++ b/pages/tags/decorator.md
@@ -0,0 +1,37 @@
+---
+layout: page
+title: '@decorator'
+navigation_source: docs_nav
+---
+
+| Standardization: | [Extended]({% link pages/spec/standardization_groups.md %}) |
+| Syntax kind: | [Block tag]({% link pages/spec/tag_kinds.md %}) |
+
+
+## Usage
+
+[ECMAScript decorators](https://www.typescriptlang.org/docs/handbook/decorators.html) are sometimes an important part
+of an API contract.  However, today the TypeScript compiler does not represent decorators in the .d.ts output files
+used by API consumers.  The `@decorator` tag provides a workaround, enabling a decorator expression to be quoted
+in a doc comment.
+
+
+## Example
+
+```ts
+class Book {
+  /**
+   * The title of the book.
+   * @decorator `@jsonSerialized`
+   * @decorator `@jsonFormat(JsonFormats.Url)`
+   */
+  @jsonSerialized
+  @jsonFormat(JsonFormats.Url)
+  public website: string;
+}
+```
+
+
+## See also
+
+- [RFC #271](https://github.com/microsoft/tsdoc/issues/271): `@decorator` tag for documenting ECMAScript decorators