From 2417239a01cf9e6ac12fa98e361962b2ed0fb339 Mon Sep 17 00:00:00 2001
From: Travis Prescott <tjprescott@users.noreply.github.com>
Date: Mon, 28 Aug 2023 15:27:41 -0700
Subject: [PATCH] Document comment styles and how to document APIs (#2336)

Fixes #2312.
---
 docs/language-basics/documentation.md | 74 +++++++++++++++++++++++++++
 packages/website/sidebars.js          |  1 +
 2 files changed, 75 insertions(+)
 create mode 100644 docs/language-basics/documentation.md

diff --git a/docs/language-basics/documentation.md b/docs/language-basics/documentation.md
new file mode 100644
index 000000000..d8ce3e780
--- /dev/null
+++ b/docs/language-basics/documentation.md
@@ -0,0 +1,74 @@
+---
+id: documentation
+title: Documentation
+---
+
+# Documentation
+
+Documentation is crucial to any API. TypeSpec provides a number of ways to document your API using TSDoc doc comments and decorators.
+
+# Documenting APIs
+
+## `@doc` Decorator
+
+The `@doc` decorator can be used to attach documentation to most TypeSpec declarations. It most-commonly accepts a string argument that will be used as the documentation for the declaration.
+
+```typespec
+@doc("This is a sample model")
+model Dog {
+  @doc("This is a sample property")
+  name: string;
+}
+```
+
+The `@doc` decorator can also accept a source object which can be used, for example, to provide templated documentation for a generic type.
+
+```typespec
+@doc("Templated {name}", T)
+model Template<T extends {}>  {
+}
+
+// doc will read "Templated A"
+model A is Template<A>
+```
+
+## TSDoc Doc Comments
+
+TSDoc doc comments are a standard way to document TypeScript code. They are supported by many IDEs and can be used to generate external documentation using tools like [TypeDoc](https://typedoc.org/).
+
+You can annotate objects in your TypeSpec spec with TSDoc doc comments. These comments will be considered the same as if they were attached using the `@doc` decorator and can be used to generate external documentation.
+
+```typespec
+/**
+ * Get a widget.
+ * @param widgetId The ID of the widget to retrieve.
+ * /
+op @get create(@path widgetId: string): Widget | Error;
+```
+
+This is functionally equivalent to:
+
+```typespec
+@doc("Get a widget.")
+op @get create(
+  @doc("The ID of the widget to retrieve.")
+  @path
+  widgetId: string): Widget | Error;
+```
+
+The benefit to using TSDoc doc comment syntax is that it keeps all of the documentation for a declaration in one place, making it easier to read and maintain. Additionally, it allows the generation of documentation using tools like TypeDoc without having to write a custom emitter to examine the `@doc` metadata.
+
+# Comments
+
+TypeSpec supports both single-line and multi-line comments. Single-line comments start with `//` and continue until the end of the line. Multi-line comments start with `/*` and continue until the closing `*/` is encountered.
+
+```typespec
+// This is a single-line comment
+model Dog {
+  /* This is a multi-line comment
+  that spans multiple lines */
+  name: string;
+}
+```
+
+Comments are ignored by the compiler and are not included in the generated output. They are intended to be used to document your spec internally and are not suitable for generating external documentation.
diff --git a/packages/website/sidebars.js b/packages/website/sidebars.js
index ee45c0816..26eaa1fdc 100644
--- a/packages/website/sidebars.js
+++ b/packages/website/sidebars.js
@@ -65,6 +65,7 @@ const sidebars = {
         "language-basics/imports",
         "language-basics/namespaces",
         "language-basics/decorators",
+        "language-basics/documentation",
         "language-basics/scalars",
         "language-basics/models",
         "language-basics/operations",