From edc9e69f30084a108f960dee18b6ad9c8298dedd Mon Sep 17 00:00:00 2001
From: Cory LaViska <cory@abeautifulsite.net>
Date: Thu, 12 Jan 2023 10:26:25 -0500
Subject: [PATCH] add @documentation tag

---
 custom-elements-manifest.config.js                    | 3 ++-
 docs/components/qr-code.md                            | 2 --
 docs/resources/changelog.md                           | 1 +
 scripts/plop/templates/component/component.hbs        | 4 ++--
 src/components/alert/alert.ts                         | 4 ++--
 src/components/animated-image/animated-image.ts       | 4 ++--
 src/components/animation/animation.ts                 | 4 ++--
 src/components/avatar/avatar.ts                       | 4 ++--
 src/components/badge/badge.ts                         | 4 ++--
 src/components/breadcrumb-item/breadcrumb-item.ts     | 4 ++--
 src/components/breadcrumb/breadcrumb.ts               | 4 ++--
 src/components/button-group/button-group.ts           | 4 ++--
 src/components/button/button.ts                       | 4 ++--
 src/components/card/card.ts                           | 4 ++--
 src/components/checkbox/checkbox.ts                   | 4 ++--
 src/components/color-picker/color-picker.ts           | 4 ++--
 src/components/details/details.ts                     | 4 ++--
 src/components/dialog/dialog.ts                       | 4 ++--
 src/components/divider/divider.ts                     | 4 ++--
 src/components/drawer/drawer.ts                       | 4 ++--
 src/components/dropdown/dropdown.ts                   | 4 ++--
 src/components/format-bytes/format-bytes.ts           | 4 ++--
 src/components/format-date/format-date.ts             | 4 ++--
 src/components/format-number/format-number.ts         | 4 ++--
 src/components/icon-button/icon-button.ts             | 4 ++--
 src/components/icon/icon.ts                           | 4 ++--
 src/components/image-comparer/image-comparer.ts       | 4 ++--
 src/components/include/include.ts                     | 4 ++--
 src/components/input/input.ts                         | 4 ++--
 src/components/menu-item/menu-item.ts                 | 4 ++--
 src/components/menu-label/menu-label.ts               | 4 ++--
 src/components/menu/menu.ts                           | 4 ++--
 src/components/mutation-observer/mutation-observer.ts | 4 ++--
 src/components/option/option.ts                       | 4 ++--
 src/components/popup/popup.ts                         | 4 ++--
 src/components/progress-bar/progress-bar.ts           | 4 ++--
 src/components/progress-ring/progress-ring.ts         | 4 ++--
 src/components/qr-code/qr-code.ts                     | 4 +++-
 src/components/radio-button/radio-button.ts           | 4 ++--
 src/components/radio-group/radio-group.ts             | 4 ++--
 src/components/radio/radio.ts                         | 4 ++--
 src/components/range/range.ts                         | 4 ++--
 src/components/rating/rating.ts                       | 4 ++--
 src/components/relative-time/relative-time.ts         | 4 ++--
 src/components/resize-observer/resize-observer.ts     | 4 ++--
 src/components/select/select.ts                       | 4 ++--
 src/components/skeleton/skeleton.ts                   | 6 +++---
 src/components/spinner/spinner.ts                     | 4 ++--
 src/components/split-panel/split-panel.ts             | 4 ++--
 src/components/switch/switch.ts                       | 4 ++--
 src/components/tab-group/tab-group.ts                 | 4 ++--
 src/components/tab-panel/tab-panel.ts                 | 4 ++--
 src/components/tab/tab.ts                             | 4 ++--
 src/components/tag/tag.ts                             | 4 ++--
 src/components/textarea/textarea.ts                   | 4 ++--
 src/components/tooltip/tooltip.ts                     | 4 ++--
 src/components/tree-item/tree-item.ts                 | 4 ++--
 src/components/tree/tree.ts                           | 4 ++--
 src/components/visually-hidden/visually-hidden.ts     | 4 ++--
 59 files changed, 117 insertions(+), 115 deletions(-)

diff --git a/custom-elements-manifest.config.js b/custom-elements-manifest.config.js
index b82161e0..b13a7899 100644
--- a/custom-elements-manifest.config.js
+++ b/custom-elements-manifest.config.js
@@ -45,7 +45,7 @@ export default {
           case ts.SyntaxKind.ClassDeclaration: {
             const className = node.name.getText();
             const classDoc = moduleDoc?.declarations?.find(declaration => declaration.name === className);
-            const customTags = ['title', 'animation', 'dependency', 'since', 'status'];
+            const customTags = ['animation', 'dependency', 'documentation', 'since', 'status', 'title'];
             let customComments = '/**';
 
             node.jsDoc?.forEach(jsDoc => {
@@ -81,6 +81,7 @@ export default {
                   break;
 
                 // Value-only metadata tags
+                case 'documentation':
                 case 'since':
                 case 'status':
                 case 'title':
diff --git a/docs/components/qr-code.md b/docs/components/qr-code.md
index 968c4d15..cddc9a75 100644
--- a/docs/components/qr-code.md
+++ b/docs/components/qr-code.md
@@ -2,8 +2,6 @@
 
 [component-header:sl-qr-code]
 
-Generates a [QR code](https://www.qrcode.com/) and renders it using the [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API).
-
 QR codes are useful for providing small pieces of information to users who can quickly scan them with a smartphone. Most smartphones have built-in QR code scanners, so simply pointing the camera at a QR code will decode it and allow the user to visit a website, dial a phone number, read a message, etc.
 
 ```html preview
diff --git a/docs/resources/changelog.md b/docs/resources/changelog.md
index 40c545ba..030ffe93 100644
--- a/docs/resources/changelog.md
+++ b/docs/resources/changelog.md
@@ -13,6 +13,7 @@ New versions of Shoelace are released as-needed and generally occur when a criti
 - Added support for the `inert` attribute on `<sl-menu-item>` to allow hidden menu items to not accept focus [#1107](https://github.com/shoelace-style/shoelace/issues/1107)
 - Added the `tag` part to `<sl-select>`
 - Added `sl-hover` event to `<sl-rating>` [#1125](https://github.com/shoelace-style/shoelace/issues/1125)
+- Added the `@documentation` tag with a link to the docs for each component
 - Fixed a bug in `<sl-select>` that prevented placeholders from showing when `multiple` was used [#1109](https://github.com/shoelace-style/shoelace/issues/1109)
 - Fixed a bug in `<sl-select>` that caused tags to not be rounded when using the `pill` attribute [#1117](https://github.com/shoelace-style/shoelace/issues/1117)
 - Fixed a bug in `<sl-select>` where the `sl-change` and `sl-input` events didn't weren't emitted when removing tags [#1119](https://github.com/shoelace-style/shoelace/issues/1119)
diff --git a/scripts/plop/templates/component/component.hbs b/scripts/plop/templates/component/component.hbs
index 7bb28a0d..fa0dfc66 100644
--- a/scripts/plop/templates/component/component.hbs
+++ b/scripts/plop/templates/component/component.hbs
@@ -8,9 +8,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Short summary of the component's intended use.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/{{ tagWithoutPrefix tag }}
  * @status experimental
+ * @since 2.0
  *
  * @dependency sl-example
  *
diff --git a/src/components/alert/alert.ts b/src/components/alert/alert.ts
index 961f9896..f61288e3 100644
--- a/src/components/alert/alert.ts
+++ b/src/components/alert/alert.ts
@@ -16,9 +16,9 @@ const toastStack = Object.assign(document.createElement('div'), { className: 'sl
 
 /**
  * @summary Alerts are used to display important messages inline or as toast notifications.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/alert
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon-button
  *
diff --git a/src/components/animated-image/animated-image.ts b/src/components/animated-image/animated-image.ts
index 33795a88..eba624a4 100644
--- a/src/components/animated-image/animated-image.ts
+++ b/src/components/animated-image/animated-image.ts
@@ -8,9 +8,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary A component for displaying animated GIFs and WEBPs that play and pause on interaction.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/animated-image
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/animation/animation.ts b/src/components/animation/animation.ts
index 6e9082dd..e225b3b2 100644
--- a/src/components/animation/animation.ts
+++ b/src/components/animation/animation.ts
@@ -8,9 +8,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Animate elements declaratively with nearly 100 baked-in presets, or roll your own with custom keyframes. Powered by the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/animation
  * @status stable
+ * @since 2.0
  *
  * @event sl-cancel - Emitted when the animation is canceled.
  * @event sl-finish - Emitted when the animation finishes.
diff --git a/src/components/avatar/avatar.ts b/src/components/avatar/avatar.ts
index 78c529df..ae0e7fe5 100644
--- a/src/components/avatar/avatar.ts
+++ b/src/components/avatar/avatar.ts
@@ -9,9 +9,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Avatars are used to represent a person or object.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/avatar
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/badge/badge.ts b/src/components/badge/badge.ts
index 17b97926..491d631f 100644
--- a/src/components/badge/badge.ts
+++ b/src/components/badge/badge.ts
@@ -7,9 +7,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Badges are used to draw attention and display statuses or counts.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/badge
  * @status stable
+ * @since 2.0
  *
  * @slot - The badge's content.
  *
diff --git a/src/components/breadcrumb-item/breadcrumb-item.ts b/src/components/breadcrumb-item/breadcrumb-item.ts
index 5d26fdf9..dda0ccb4 100644
--- a/src/components/breadcrumb-item/breadcrumb-item.ts
+++ b/src/components/breadcrumb-item/breadcrumb-item.ts
@@ -9,9 +9,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Breadcrumb Items are used inside [breadcrumbs](/components/breadcrumb) to represent different links.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/breadcrumb-item
  * @status stable
+ * @since 2.0
  *
  * @slot - The breadcrumb item's label.
  * @slot prefix - An optional prefix, usually an icon or icon button.
diff --git a/src/components/breadcrumb/breadcrumb.ts b/src/components/breadcrumb/breadcrumb.ts
index 7f30a238..90dc4008 100644
--- a/src/components/breadcrumb/breadcrumb.ts
+++ b/src/components/breadcrumb/breadcrumb.ts
@@ -9,9 +9,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Breadcrumbs provide a group of links so users can easily navigate a website's hierarchy.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/breadcrumb
  * @status stable
+ * @since 2.0
  *
  * @slot - One or more breadcrumb items to display.
  * @slot separator - The separator to use between breadcrumb items. Works best with `<sl-icon>`.
diff --git a/src/components/button-group/button-group.ts b/src/components/button-group/button-group.ts
index ef26022b..3ab264d9 100644
--- a/src/components/button-group/button-group.ts
+++ b/src/components/button-group/button-group.ts
@@ -6,9 +6,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Button groups can be used to group related buttons into sections.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/button-group
  * @status stable
+ * @since 2.0
  *
  * @slot - One or more `<sl-button>` elements to display in the button group.
  *
diff --git a/src/components/button/button.ts b/src/components/button/button.ts
index ce6012d8..444175e3 100644
--- a/src/components/button/button.ts
+++ b/src/components/button/button.ts
@@ -15,9 +15,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Buttons represent actions that are available to the user.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/button
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  * @dependency sl-spinner
diff --git a/src/components/card/card.ts b/src/components/card/card.ts
index 4eae9b13..f60663b1 100644
--- a/src/components/card/card.ts
+++ b/src/components/card/card.ts
@@ -8,9 +8,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Cards can be used to group related subjects in a container.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/card
  * @status stable
+ * @since 2.0
  *
  * @slot - The card's main content.
  * @slot header - An optional header for the card.
diff --git a/src/components/checkbox/checkbox.ts b/src/components/checkbox/checkbox.ts
index 7e89fbf6..d988181f 100644
--- a/src/components/checkbox/checkbox.ts
+++ b/src/components/checkbox/checkbox.ts
@@ -14,9 +14,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Checkboxes allow the user to toggle an option on or off.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/checkbox
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/color-picker/color-picker.ts b/src/components/color-picker/color-picker.ts
index 4fba75c7..b85b6673 100644
--- a/src/components/color-picker/color-picker.ts
+++ b/src/components/color-picker/color-picker.ts
@@ -37,9 +37,9 @@ declare const EyeDropper: EyeDropperConstructor;
 
 /**
  * @summary Color pickers allow the user to select a color.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/color-picker
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-button
  * @dependency sl-button-group
diff --git a/src/components/details/details.ts b/src/components/details/details.ts
index 9420d81a..32278ebe 100644
--- a/src/components/details/details.ts
+++ b/src/components/details/details.ts
@@ -13,9 +13,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Details show a brief summary and expand to show additional content.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/details
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/dialog/dialog.ts b/src/components/dialog/dialog.ts
index 2d3c897d..074b22cd 100644
--- a/src/components/dialog/dialog.ts
+++ b/src/components/dialog/dialog.ts
@@ -17,9 +17,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Dialogs, sometimes called "modals", appear above the page and require the user's immediate attention.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/dialog
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon-button
  *
diff --git a/src/components/divider/divider.ts b/src/components/divider/divider.ts
index 2c85b516..8ac1b55f 100644
--- a/src/components/divider/divider.ts
+++ b/src/components/divider/divider.ts
@@ -6,9 +6,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Dividers are used to visually separate or group elements.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/divider
  * @status stable
+ * @since 2.0
  *
  * @cssproperty --color - The color of the divider.
  * @cssproperty --width - The width of the divider.
diff --git a/src/components/drawer/drawer.ts b/src/components/drawer/drawer.ts
index f3abd7df..fef6afd6 100644
--- a/src/components/drawer/drawer.ts
+++ b/src/components/drawer/drawer.ts
@@ -18,9 +18,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Drawers slide in from a container to expose additional options and information.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/drawer
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon-button
  *
diff --git a/src/components/dropdown/dropdown.ts b/src/components/dropdown/dropdown.ts
index 355894ac..032f272a 100644
--- a/src/components/dropdown/dropdown.ts
+++ b/src/components/dropdown/dropdown.ts
@@ -20,9 +20,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Dropdowns expose additional content that "drops down" in a panel.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/dropdown
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-popup
  *
diff --git a/src/components/format-bytes/format-bytes.ts b/src/components/format-bytes/format-bytes.ts
index 5c978f57..c1dde3ec 100644
--- a/src/components/format-bytes/format-bytes.ts
+++ b/src/components/format-bytes/format-bytes.ts
@@ -4,9 +4,9 @@ import { LocalizeController } from '../../utilities/localize';
 
 /**
  * @summary Formats a number as a human readable bytes value.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/format-bytes
  * @status stable
+ * @since 2.0
  */
 @customElement('sl-format-bytes')
 export default class SlFormatBytes extends ShoelaceElement {
diff --git a/src/components/format-date/format-date.ts b/src/components/format-date/format-date.ts
index 7298f126..583511de 100644
--- a/src/components/format-date/format-date.ts
+++ b/src/components/format-date/format-date.ts
@@ -5,9 +5,9 @@ import { LocalizeController } from '../../utilities/localize';
 
 /**
  * @summary Formats a date/time using the specified locale and options.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/format-date
  * @status stable
+ * @since 2.0
  */
 @customElement('sl-format-date')
 export default class SlFormatDate extends ShoelaceElement {
diff --git a/src/components/format-number/format-number.ts b/src/components/format-number/format-number.ts
index de8b9f18..0ae36c07 100644
--- a/src/components/format-number/format-number.ts
+++ b/src/components/format-number/format-number.ts
@@ -4,9 +4,9 @@ import { LocalizeController } from '../../utilities/localize';
 
 /**
  * @summary Formats a number using the specified locale and options.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/format-number
  * @status stable
+ * @since 2.0
  */
 @customElement('sl-format-number')
 export default class SlFormatNumber extends ShoelaceElement {
diff --git a/src/components/icon-button/icon-button.ts b/src/components/icon-button/icon-button.ts
index 3a86138f..091ad140 100644
--- a/src/components/icon-button/icon-button.ts
+++ b/src/components/icon-button/icon-button.ts
@@ -9,9 +9,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Icons buttons are simple, icon-only buttons that can be used for actions and in toolbars.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/icon-button
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/icon/icon.ts b/src/components/icon/icon.ts
index 18b5e3ba..dca4c061 100644
--- a/src/components/icon/icon.ts
+++ b/src/components/icon/icon.ts
@@ -12,9 +12,9 @@ let parser: DOMParser;
 
 /**
  * @summary Icons are symbols that can be used to represent various options within an application.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/icon
  * @status stable
+ * @since 2.0
  *
  * @event sl-load - Emitted when the icon has loaded.
  * @event sl-error - Emitted when the icon fails to load due to an error.
diff --git a/src/components/image-comparer/image-comparer.ts b/src/components/image-comparer/image-comparer.ts
index f6160341..c513617e 100644
--- a/src/components/image-comparer/image-comparer.ts
+++ b/src/components/image-comparer/image-comparer.ts
@@ -13,9 +13,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Compare visual differences between similar photos with a sliding panel.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/image-comparer
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/include/include.ts b/src/components/include/include.ts
index 9be52be4..0122a92c 100644
--- a/src/components/include/include.ts
+++ b/src/components/include/include.ts
@@ -8,9 +8,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Includes give you the power to embed external HTML files into the page.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/include
  * @status stable
+ * @since 2.0
  *
  * @event sl-load - Emitted when the included file is loaded.
  * @event {{ status: number }} sl-error - Emitted when the included file fails to load due to an error.
diff --git a/src/components/input/input.ts b/src/components/input/input.ts
index 55eb12b5..03ad4c17 100644
--- a/src/components/input/input.ts
+++ b/src/components/input/input.ts
@@ -28,9 +28,9 @@ const isFirefox = isChromium ? false : navigator.userAgent.includes('Firefox');
 
 /**
  * @summary Inputs collect data from the user.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/input
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/menu-item/menu-item.ts b/src/components/menu-item/menu-item.ts
index d940b06b..87eea265 100644
--- a/src/components/menu-item/menu-item.ts
+++ b/src/components/menu-item/menu-item.ts
@@ -10,9 +10,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Menu items provide options for the user to pick from in a menu.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/menu-item
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/menu-label/menu-label.ts b/src/components/menu-label/menu-label.ts
index 7c4e4e94..bcecbe9f 100644
--- a/src/components/menu-label/menu-label.ts
+++ b/src/components/menu-label/menu-label.ts
@@ -6,9 +6,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Menu labels are used to describe a group of menu items.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/menu-label
  * @status stable
+ * @since 2.0
  *
  * @slot - The menu label's content.
  *
diff --git a/src/components/menu/menu.ts b/src/components/menu/menu.ts
index b507716f..d84ec827 100644
--- a/src/components/menu/menu.ts
+++ b/src/components/menu/menu.ts
@@ -10,9 +10,9 @@ export interface MenuSelectEventDetail {
 
 /**
  * @summary Menus provide a list of options for the user to choose from.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/menu
  * @status stable
+ * @since 2.0
  *
  * @slot - The menu's content, including menu items, menu labels, and dividers.
  *
diff --git a/src/components/mutation-observer/mutation-observer.ts b/src/components/mutation-observer/mutation-observer.ts
index 4231b7fd..07a2f6aa 100644
--- a/src/components/mutation-observer/mutation-observer.ts
+++ b/src/components/mutation-observer/mutation-observer.ts
@@ -7,9 +7,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary The Mutation Observer component offers a thin, declarative interface to the [`MutationObserver API`](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/mutation-observer
  * @status stable
+ * @since 2.0
  *
  * @event {{ mutationList: MutationRecord[] }} sl-mutation - Emitted when a mutation occurs.
  *
diff --git a/src/components/option/option.ts b/src/components/option/option.ts
index a1b8696b..82e476f8 100644
--- a/src/components/option/option.ts
+++ b/src/components/option/option.ts
@@ -10,9 +10,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Options define the selectable items within various form controls such as [select](/components/select).
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/option
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/popup/popup.ts b/src/components/popup/popup.ts
index 6ebf82da..0c15b4e8 100644
--- a/src/components/popup/popup.ts
+++ b/src/components/popup/popup.ts
@@ -8,9 +8,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Popup is a utility that lets you declaratively anchor "popup" containers to another element.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/popup
  * @status stable
+ * @since 2.0
  *
  * @event sl-reposition - Emitted when the popup is repositioned. This event can fire a lot, so avoid putting expensive
  *  operations in your listener or consider debouncing it.
diff --git a/src/components/progress-bar/progress-bar.ts b/src/components/progress-bar/progress-bar.ts
index 29545803..0ed0154b 100644
--- a/src/components/progress-bar/progress-bar.ts
+++ b/src/components/progress-bar/progress-bar.ts
@@ -10,9 +10,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Progress bars are used to show the status of an ongoing operation.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/progress-bar
  * @status stable
+ * @since 2.0
  *
  * @slot - A label to show inside the progress indicator.
  *
diff --git a/src/components/progress-ring/progress-ring.ts b/src/components/progress-ring/progress-ring.ts
index 3b7a4f23..41d3d098 100644
--- a/src/components/progress-ring/progress-ring.ts
+++ b/src/components/progress-ring/progress-ring.ts
@@ -7,9 +7,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Progress rings are used to show the progress of a determinate operation in a circular fashion.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/progress-ring
  * @status stable
+ * @since 2.0
  *
  * @slot - A label to show inside the ring.
  *
diff --git a/src/components/qr-code/qr-code.ts b/src/components/qr-code/qr-code.ts
index 9facaf6b..d6a0a9fc 100644
--- a/src/components/qr-code/qr-code.ts
+++ b/src/components/qr-code/qr-code.ts
@@ -8,8 +8,10 @@ import styles from './qr-code.styles';
 import type { CSSResultGroup } from 'lit';
 
 /**
- * @since 2.0
+ * @summary Generates a [QR code](https://www.qrcode.com/) and renders it using the [Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API).
+ * @documentation https://shoelace.style/components/qr-code
  * @status stable
+ * @since 2.0
  *
  * @csspart base - The component's base wrapper.
  */
diff --git a/src/components/radio-button/radio-button.ts b/src/components/radio-button/radio-button.ts
index 1b153b8b..50ce1879 100644
--- a/src/components/radio-button/radio-button.ts
+++ b/src/components/radio-button/radio-button.ts
@@ -10,9 +10,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Radios buttons allow the user to select a single option from a group using a button-like control.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/radio-button
  * @status stable
+ * @since 2.0
  *
  * @slot - The radio button's label.
  * @slot prefix - A presentational prefix icon or similar element.
diff --git a/src/components/radio-group/radio-group.ts b/src/components/radio-group/radio-group.ts
index 0b396767..5e93d38b 100644
--- a/src/components/radio-group/radio-group.ts
+++ b/src/components/radio-group/radio-group.ts
@@ -14,9 +14,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Radio groups are used to group multiple [radios](/components/radio) or [radio buttons](/components/radio-button) so they function as a single form control.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/radio-group
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-button-group
  *
diff --git a/src/components/radio/radio.ts b/src/components/radio/radio.ts
index a3576fab..18819f10 100644
--- a/src/components/radio/radio.ts
+++ b/src/components/radio/radio.ts
@@ -9,9 +9,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Radios allow the user to select a single option from a group.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/radio
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/range/range.ts b/src/components/range/range.ts
index 3198aa49..d5b2b132 100644
--- a/src/components/range/range.ts
+++ b/src/components/range/range.ts
@@ -15,9 +15,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Ranges allow the user to select a single value within a given range using a slider.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/range
  * @status stable
+ * @since 2.0
  *
  * @slot label - The range's label. Alternatively, you can use the `label` attribute.
  * @slot help-text - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
diff --git a/src/components/rating/rating.ts b/src/components/rating/rating.ts
index 84e57ff1..ac82f335 100644
--- a/src/components/rating/rating.ts
+++ b/src/components/rating/rating.ts
@@ -13,9 +13,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Ratings give users a way to quickly view and provide feedback.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/rating
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  *
diff --git a/src/components/relative-time/relative-time.ts b/src/components/relative-time/relative-time.ts
index ea2c8bef..f57b560d 100644
--- a/src/components/relative-time/relative-time.ts
+++ b/src/components/relative-time/relative-time.ts
@@ -20,9 +20,9 @@ const availableUnits: UnitConfig[] = [
 
 /**
  * @summary Outputs a localized time phrase relative to the current date and time.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/relative-time
  * @status stable
+ * @since 2.0
  */
 @customElement('sl-relative-time')
 export default class SlRelativeTime extends ShoelaceElement {
diff --git a/src/components/resize-observer/resize-observer.ts b/src/components/resize-observer/resize-observer.ts
index c63a6a78..0f5abc9e 100644
--- a/src/components/resize-observer/resize-observer.ts
+++ b/src/components/resize-observer/resize-observer.ts
@@ -7,9 +7,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary The Resize Observer component offers a thin, declarative interface to the [`ResizeObserver API`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/resize-observer
  * @status stable
+ * @since 2.0
  *
  * @slot - One or more elements to watch for resizing.
  *
diff --git a/src/components/select/select.ts b/src/components/select/select.ts
index 5330560c..955e8895 100644
--- a/src/components/select/select.ts
+++ b/src/components/select/select.ts
@@ -22,9 +22,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Selects allow you to choose items from a menu of predefined options.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/select
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon
  * @dependency sl-popup
diff --git a/src/components/skeleton/skeleton.ts b/src/components/skeleton/skeleton.ts
index 1a795408..cec161cd 100644
--- a/src/components/skeleton/skeleton.ts
+++ b/src/components/skeleton/skeleton.ts
@@ -6,10 +6,10 @@ import styles from './skeleton.styles';
 import type { CSSResultGroup } from 'lit';
 
 /**
- * @summary Skeletons are used to show where content will eventually be drawn.
- *
- * @since 2.0
+ * @summary Skeletons are used to provide a visual representation of where content will eventually be drawn.
+ * @documentation https://shoelace.style/components/skeleton
  * @status stable
+ * @since 2.0
  *
  * @csspart base - The component's base wrapper.
  * @csspart indicator - The skeleton's indicator which is responsible for its color and animation.
diff --git a/src/components/spinner/spinner.ts b/src/components/spinner/spinner.ts
index 457a2df5..54867bca 100644
--- a/src/components/spinner/spinner.ts
+++ b/src/components/spinner/spinner.ts
@@ -7,9 +7,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Spinners are used to show the progress of an indeterminate operation.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/spinner
  * @status stable
+ * @since 2.0
  *
  * @csspart base - The component's base wrapper.
  *
diff --git a/src/components/split-panel/split-panel.ts b/src/components/split-panel/split-panel.ts
index 63a20241..14e61d42 100644
--- a/src/components/split-panel/split-panel.ts
+++ b/src/components/split-panel/split-panel.ts
@@ -11,9 +11,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Split panels display two adjacent panels, allowing the user to reposition them.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/split-panel
  * @status stable
+ * @since 2.0
  *
  * @event sl-reposition - Emitted when the divider's position changes.
  *
diff --git a/src/components/switch/switch.ts b/src/components/switch/switch.ts
index 9a98d1cb..21f14edc 100644
--- a/src/components/switch/switch.ts
+++ b/src/components/switch/switch.ts
@@ -13,9 +13,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Switches allow the user to toggle an option on or off.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/switch
  * @status stable
+ * @since 2.0
  *
  * @slot - The switch's label.
  *
diff --git a/src/components/tab-group/tab-group.ts b/src/components/tab-group/tab-group.ts
index 38570aaf..d287c4fc 100644
--- a/src/components/tab-group/tab-group.ts
+++ b/src/components/tab-group/tab-group.ts
@@ -13,9 +13,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Tab groups organize content into a container that shows one section at a time.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/tab-group
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon-button
  *
diff --git a/src/components/tab-panel/tab-panel.ts b/src/components/tab-panel/tab-panel.ts
index 3e078991..5e08aff2 100644
--- a/src/components/tab-panel/tab-panel.ts
+++ b/src/components/tab-panel/tab-panel.ts
@@ -10,9 +10,9 @@ let id = 0;
 
 /**
  * @summary Tab panels are used inside [tab groups](/components/tab-group) to display tabbed content.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/tab-panel
  * @status stable
+ * @since 2.0
  *
  * @slot - The tab panel's content.
  *
diff --git a/src/components/tab/tab.ts b/src/components/tab/tab.ts
index 7d78b696..efb2e96b 100644
--- a/src/components/tab/tab.ts
+++ b/src/components/tab/tab.ts
@@ -12,9 +12,9 @@ let id = 0;
 
 /**
  * @summary Tabs are used inside [tab groups](/components/tab-group) to represent and activate [tab panels](/components/tab-panel).
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/tab
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon-button
  *
diff --git a/src/components/tag/tag.ts b/src/components/tag/tag.ts
index 30ed36f4..378877e5 100644
--- a/src/components/tag/tag.ts
+++ b/src/components/tag/tag.ts
@@ -9,9 +9,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Tags are used as labels to organize things or to indicate a selection.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/tag
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-icon-button
  *
diff --git a/src/components/textarea/textarea.ts b/src/components/textarea/textarea.ts
index a6c3ce26..a23d5818 100644
--- a/src/components/textarea/textarea.ts
+++ b/src/components/textarea/textarea.ts
@@ -14,9 +14,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Textareas collect data from the user and allow multiple lines of text.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/textarea
  * @status stable
+ * @since 2.0
  *
  * @slot label - The textarea's label. Alternatively, you can use the `label` attribute.
  * @slot help-text - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
diff --git a/src/components/tooltip/tooltip.ts b/src/components/tooltip/tooltip.ts
index 8c3f7134..e7ebac04 100644
--- a/src/components/tooltip/tooltip.ts
+++ b/src/components/tooltip/tooltip.ts
@@ -14,9 +14,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary Tooltips display additional information based on a specific action.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/tooltip
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-popup
  *
diff --git a/src/components/tree-item/tree-item.ts b/src/components/tree-item/tree-item.ts
index 94051cdd..279b9dbc 100644
--- a/src/components/tree-item/tree-item.ts
+++ b/src/components/tree-item/tree-item.ts
@@ -16,9 +16,9 @@ import type { CSSResultGroup, PropertyValueMap } from 'lit';
 
 /**
  * @summary A tree item serves as a hierarchical node that lives inside a [tree](/components/tree).
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/tree-item
  * @status stable
+ * @since 2.0
  *
  * @dependency sl-checkbox
  * @dependency sl-icon
diff --git a/src/components/tree/tree.ts b/src/components/tree/tree.ts
index 9dffd725..2d338a6a 100644
--- a/src/components/tree/tree.ts
+++ b/src/components/tree/tree.ts
@@ -50,9 +50,9 @@ function syncCheckboxes(changedTreeItem: SlTreeItem, initialSync = false) {
 
 /**
  * @summary Trees allow you to display a hierarchical list of selectable [tree items](/components/tree-item). Items with children can be expanded and collapsed as desired by the user.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/tree
  * @status stable
+ * @since 2.0
  *
  * @event {{ selection: TreeItem[] }} sl-selection-change - Emitted when a tree item is selected or deselected.
  *
diff --git a/src/components/visually-hidden/visually-hidden.ts b/src/components/visually-hidden/visually-hidden.ts
index 740db7ba..d54b56ba 100644
--- a/src/components/visually-hidden/visually-hidden.ts
+++ b/src/components/visually-hidden/visually-hidden.ts
@@ -6,9 +6,9 @@ import type { CSSResultGroup } from 'lit';
 
 /**
  * @summary The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
- *
- * @since 2.0
+ * @documentation https://shoelace.style/components/visually-hidden
  * @status stable
+ * @since 2.0
  *
  * @slot - The content to be visually hidden.
  */