Add docs for directives (#5014)

fix #4864 fix #3269 --------- Co-authored-by: Christopher Radek <[email protected]>
microsoft · Nov 7, 2024 · fdd69d6 · fdd69d6
1 parent 5fbd088
commit fdd69d6
Show file tree

Hide file tree

Showing 6 changed files with 95 additions and 2 deletions.
diff --git a/.chronus/changes/docs-directives-2024-10-7-18-13-59.md b/.chronus/changes/docs-directives-2024-10-7-18-13-59.md
@@ -0,0 +1,6 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: internal
+packages:
+  - "@typespec/compiler"
+---
diff --git a/packages/compiler/generated-defs/TypeSpec.ts b/packages/compiler/generated-defs/TypeSpec.ts
@@ -173,7 +173,7 @@ export type ErrorsDocDecorator = (
  *
  * NOTE: This decorator **should not** be used, use the `#deprecated` directive instead.
  *
- * @deprecated Use the `#deprecated` directive instead.
+ * @deprecated Use the `#deprecated` [directive](https://typespec.io/docs/language-basics/directives/#deprecated) instead.
  * @param message Deprecation message.
  * @example
  * Use the `#deprecated` directive instead:

diff --git a/packages/compiler/lib/std/decorators.tsp b/packages/compiler/lib/std/decorators.tsp
@@ -60,7 +60,7 @@ extern dec errorsDoc(target: Operation, doc: valueof string);
  *
  * NOTE: This decorator **should not** be used, use the `#deprecated` directive instead.
  *
- * @deprecated Use the `#deprecated` directive instead.
+ * @deprecated Use the `#deprecated` [directive](https://typespec.io/docs/language-basics/directives/#deprecated) instead.
  * @param message Deprecation message.
  *
  * @example

diff --git a/website/src/content/current-sidebar.ts b/website/src/content/current-sidebar.ts
@@ -70,6 +70,7 @@ const sidebar: SidebarItem[] = [
       "language-basics/imports",
       "language-basics/namespaces",
       "language-basics/decorators",
+      "language-basics/directives",
       "language-basics/documentation",
       "language-basics/scalars",
       "language-basics/models",

diff --git a/website/src/content/docs/docs/language-basics/directives.md b/website/src/content/docs/docs/language-basics/directives.md
@@ -0,0 +1,85 @@
+---
+title: Directives
+---
+
+Directives are predefined annotations that attach to the syntax nodes unlike decorators which will cary over with `model is`, `op is`, etc. This means any syntax node is able to have a directive(e.g `alias`).
+
+These are the available directives:
+
+- [#deprecated](#deprecated)
+- [#suppress](#suppress)
+
+## #deprecated
+
+The deprecated directive allows marking a node and through it its type as deprecated. It takes a single argument which is the deprecation message.
+
+```tsp
+#deprecated "Use NewUser instead"
+model LegacyUser {}
+```
+
+Using that type will result in a deprecation warning:
+
+```tsp
+model Post {
+  author: LegacyUser;
+  //      ^ warning: Deprecated: Use NewUser instead
+}
+```
+
+<!-- cspell:disable -->
+
+```ansi frame="terminal"
+$ tsp compile .
+
+Diagnostics were reported during compilation:
+
+[36mmain.tsp[39m:[33m5[39m:[33m11[39m - [33mwarning[39m[90m deprecated[39m: Deprecated: Use NewUser instead
+> 5 |   author: LegacyUser;
+    |           ^^^^^^^^^^
+
+Found  1 warning.
+```
+
+<!-- cspell:enable -->
+
+Adding another `#suppress` on a node that reports a deprecation warning will suppress the warning automatically.
+
+```tsp
+model Post {
+  #suppress "Use newAuthor property instead"
+  author: LegacyUser; // no need to also suppress the deprecated diagnostic about usage of LegacyUser
+}
+```
+
+### Api
+
+A library or emitter can check if a type was annotated with the deprecated directive using the `isDeprecated` method and/or get the message using `getDeprecationDetails`.
+
+```ts
+import { getDeprecationDetails, isDeprecated } from "@typespec/compiler";
+const isDeprecated = isDeprecated(program, type);
+const details = getDeprecationDetails(program, type);
+```
+
+## #suppress
+
+Suppress directive allows suppressing a specific warning diagnostic. It takes 2 arguments:
+
+- The diagnostic code to suppress
+- A message to justify the suppression
+
+:::note
+Errors are not suppressable
+:::
+
+```tsp
+model Post {
+  #suppress "deprecated" "We are not ready to migrate yet"
+  author: LegacyUser;
+}
+```
+
+### Api
+
+There is currently no exposed api to resolve suppresssions
diff --git a/website/src/css/custom.css b/website/src/css/custom.css
@@ -8,6 +8,7 @@
   --header-height: 50px;
   --sl-color-text-accent: var(--colorBrandForeground1);
   --sl-color-gray-5: var(--colorNeutralStroke1);
+  --sl-color-bg-inline-code: var(--ec-frm-edBg);
 }
 
 .DocSearch-Button {