docs: add jsdoc @see tag consistency (#11140)

**Related Issue:** #10083 ## Summary Add consistent use of the `@see` JSDoc references across the repo, where previously there was a mix of `see` and `@see` references. This is phase 1 of 2 for the issue, where phase 2 will require documentation updates to accommodate the JSDoc references to display on the site.
Esri · Dec 27, 2024 · 61b58b6 · 61b58b6
1 parent a261b21
commit 61b58b6
Show file tree

Hide file tree

Showing 16 changed files with 26 additions and 26 deletions.
diff --git a/packages/calcite-components/src/components/button/button.tsx b/packages/calcite-components/src/components/button/button.tsx
@@ -107,8 +107,9 @@ export class Button
 
   /**
    * Prompts the user to save the linked URL instead of navigating to it. Can be used with or without a value:
-   * Without a value, the browser will suggest a filename/extension
-   * See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-download.
+   * Without a value, the browser will suggest a filename/extension.
+   *
+   * @see [Global download attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download).
    */
   @property({ reflect: true, converter: stringOrBoolean }) download: string | boolean = false;
 

diff --git a/packages/calcite-components/src/components/color-picker-swatch/color-picker-swatch.tsx b/packages/calcite-components/src/components/color-picker-swatch/color-picker-swatch.tsx
@@ -37,7 +37,7 @@ export class ColorPickerSwatch extends LitElement {
   /**
    * The color value.
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/color_value
+   * @see [Color CSS data type](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value).
    */
   @property() color: string | null;
 
@@ -188,7 +188,7 @@ export class ColorPickerSwatch extends LitElement {
     rx: string;
 
     // note: stroke-width and clip-path are needed to hide overflowing portion of stroke
-    // see https://stackoverflow.com/a/7273346/194216
+    // @see https://stackoverflow.com/a/7273346/194216
     stroke?: string;
     strokeWidth?: string;
 

diff --git a/packages/calcite-components/src/components/color-picker/color-picker.tsx b/packages/calcite-components/src/components/color-picker/color-picker.tsx
@@ -325,8 +325,8 @@ export class ColorPicker extends LitElement implements InteractiveComponent, Loa
    *
    * @default
    *
-   * @see [CSS Color](https://developer.mozilla.org/en-US/docs/Web/CSS/color)
-   * @see [ColorValue](https://github.com/Esri/calcite-design-system/blob/dev/src/components/color-picker/interfaces.ts#L10)
+   * @see [CSS Color](https://developer.mozilla.org/en-US/docs/Web/CSS/color),
+   * @see [ColorValue](https://github.com/Esri/calcite-design-system/blob/dev/packages/calcite-components/src/components/color-picker/interfaces.ts#L10).
    */
   @property()
   get value(): ColorValue | null {

diff --git a/packages/calcite-components/src/components/dialog/dialog.tsx b/packages/calcite-components/src/components/dialog/dialog.tsx
@@ -149,7 +149,7 @@ export class Dialog
    *
    * By default, an open dialog can be dismissed by pressing the Esc key.
    *
-   * @see [Dialog Accessibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog#accessibility)
+   * @see [Dialog Accessibility](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog#accessibility).
    */
   @property({ reflect: true }) escapeDisabled = false;
 

diff --git a/packages/calcite-components/src/components/functional/FloatingArrow.tsx b/packages/calcite-components/src/components/functional/FloatingArrow.tsx
@@ -25,7 +25,7 @@ const DEFAULTS = {
  * @param floatingLayout.floatingLayout
  * @param floatingLayout – The effective floating layout to render the arrow vertically or horizontally. Possible values: `vertical` or `horizontal`.
  *
- * See [floating-ui](https://github.com/Esri/calcite-design-system/blob/dev/src/utils/floating-ui.ts)
+ * @see [floating-ui](https://github.com/Esri/calcite-design-system/blob/dev/packages/calcite-components/src/utils/floating-ui.ts).
  * @param floatingLayout.key
  * @param floatingLayout.ref
  */

diff --git a/packages/calcite-components/src/components/icon/icon.tsx b/packages/calcite-components/src/components/icon/icon.tsx
@@ -48,7 +48,7 @@ export class Icon extends LitElement {
   /**
    * Displays a specific icon.
    *
-   * @see [Icons](https://esri.github.io/calcite-ui-icons)
+   * @see [Calcite UI Icons](https://developers.arcgis.com/calcite-design-system/icons).
    */
   @property({
     reflect: true,

diff --git a/packages/calcite-components/src/components/input-date-picker/input-date-picker.tsx b/packages/calcite-components/src/components/input-date-picker/input-date-picker.tsx
@@ -630,7 +630,7 @@ export class InputDatePicker
   private handleDateTimeFormatChange(): void {
     const formattingOptions: Intl.DateTimeFormatOptions = {
       // we explicitly set numberingSystem to prevent the browser-inferred value
-      // see https://github.com/Esri/calcite-design-system/issues/3079#issuecomment-1168964195 for more info
+      // @see [Arabic numbering system support context](https://github.com/Esri/calcite-design-system/issues/3079#issuecomment-1168964195) for more info.
       numberingSystem: getSupportedNumberingSystem(this.numberingSystem),
     };
 

diff --git a/packages/calcite-components/src/components/input-time-zone/input-time-zone.tsx b/packages/calcite-components/src/components/input-time-zone/input-time-zone.tsx
@@ -168,7 +168,7 @@ export class InputTimeZone
    *
    * It can be either a Date instance or a string in ISO format (`"YYYY-MM-DD"`, `"YYYY-MM-DDTHH:MM:SS.SSSZ"`).
    *
-   * @see [Date.prototype.toISOString](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)
+   * @see [Date.prototype.toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString).
    */
   @property() referenceDate: Date | string;
 
@@ -218,7 +218,7 @@ export class InputTimeZone
    *
    * If no value is provided, the user's time zone offset will be selected by default.
    *
-   * @see https://www.w3.org/International/core/2005/09/timezone.html#:~:text=What%20is%20a%20%22zone%20offset,or%20%22%2D%22%20from%20UTC.
+   * @see [Identifying time zones and zone offsets](https://www.w3.org/International/core/2005/09/timezone.html#:~:text=What%20is%20a%20%22zone%20offset,or%20%22%2D%22%20from%20UTC).
    */
   @property()
   get value(): string {

diff --git a/packages/calcite-components/src/components/link/link.tsx b/packages/calcite-components/src/components/link/link.tsx
@@ -53,8 +53,9 @@ export class Link extends LitElement implements InteractiveComponent, LoadableCo
 
   /**
    * Prompts the user to save the linked URL instead of navigating to it. Can be used with or without a value:
-   * Without a value, the browser will suggest a filename/extension
-   * See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attr-download.
+   * Without a value, the browser will suggest a filename/extension.
+   *
+   * @see [Global download attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#download).
    */
   @property({ reflect: true, converter: stringOrBoolean }) download: string | boolean = false;
 

diff --git a/packages/calcite-components/src/components/select/select.tsx b/packages/calcite-components/src/components/select/select.tsx
@@ -293,7 +293,7 @@ export class Select
       option.value = optionOrGroup.value;
 
       // need to set innerText for mobile
-      // see https://stackoverflow.com/questions/35021620/ios-safari-not-showing-all-options-for-select-menu/41749701
+      // @see [iOS Safari now showing all options for select menu](https://stackoverflow.com/questions/35021620/ios-safari-not-showing-all-options-for-select-menu/41749701).
       option.innerText = optionOrGroup.label;
     }
   }

diff --git a/packages/calcite-components/src/components/slider/slider.tsx b/packages/calcite-components/src/components/slider/slider.tsx
@@ -209,7 +209,7 @@ export class Slider
   /**
    * A list of the histogram's x,y coordinates within the component's `min` and `max`. Displays above the component's track.
    *
-   * @see [DataSeries](https://github.com/Esri/calcite-design-system/blob/dev/src/components/graph/interfaces.ts#L5)
+   * @see [DataSeries](https://github.com/Esri/calcite-design-system/blob/dev/packages/calcite-components/src/components/graph/interfaces.ts#L5).
    */
   @property() histogram: DataSeries;
 

diff --git a/packages/calcite-components/src/components/tab-title/tab-title.tsx b/packages/calcite-components/src/components/tab-title/tab-title.tsx
@@ -204,15 +204,15 @@ export class TabTitle extends LitElement implements InteractiveComponent {
   /**
    * Fires when a `calcite-tab` is selected (`event.details`).
    *
-   * @see [TabChangeEventDetail](https://github.com/Esri/calcite-design-system/blob/dev/src/components/tab/interfaces.ts#L1)
+   * @see [TabChangeEventDetail](https://github.com/Esri/calcite-design-system/blob/dev/packages/calcite-components/src/components/tab/interfaces.ts#L1).
    * @private
    */
   calciteInternalTabsActivate = createEvent<TabChangeEventDetail>({ cancelable: false });
 
   /**
    * Fires when `calcite-tab` is closed (`event.details`).
    *
-   * @see [TabChangeEventDetail](https://github.com/Esri/calcite-design-system/blob/dev/src/components/tab/interfaces.ts)
+   * @see [TabChangeEventDetail](https://github.com/Esri/calcite-design-system/blob/dev/packages/calcite-components/src/components/tab/interfaces.ts).
    * @private
    */
   calciteInternalTabsClose = createEvent<TabCloseEventDetail>({ cancelable: false });

diff --git a/packages/calcite-components/src/tests/utils.ts b/packages/calcite-components/src/tests/utils.ts
@@ -382,7 +382,7 @@ export async function getFocusedElementProp(
 /**
  * Custom integer matcher to use with object matchers.
  *
- * @see https://jasmine.github.io/tutorials/custom_argument_matchers
+ * @see [Custom Asymmetric Equality Testers](https://jasmine.github.io/tutorials/custom_asymmetric_equality_testers).
  */
 export function toBeInteger(): any {
   return {
@@ -399,7 +399,7 @@ export function toBeInteger(): any {
 /**
  * Custom number matcher to use with object matchers.
  *
- * @see https://jasmine.github.io/tutorials/custom_argument_matchers
+ * @see [Custom Asymmetric Equality Testers](https://jasmine.github.io/tutorials/custom_asymmetric_equality_testers).
  */
 export function toBeNumber(): any {
   return {

diff --git a/packages/calcite-components/src/utils/config.ts b/packages/calcite-components/src/utils/config.ts
@@ -8,7 +8,7 @@ export interface CalciteConfig {
    *
    * This is useful if your application uses its own instance of `focus-trap` and both need to be aware of each other.
    *
-   * @see https://github.com/focus-trap/focus-trap#createoptions
+   * @see [focus-trap createOptions](https://github.com/focus-trap/focus-trap#createoptions).
    */
   focusTrapStack: FocusTrap[];
 

diff --git a/packages/calcite-components/src/utils/globalScript.ts b/packages/calcite-components/src/utils/globalScript.ts
@@ -5,7 +5,7 @@ import { isBrowser } from "./browser";
 /**
  * This file is imported in Stencil's `globalScript` config option.
  *
- * @see {@link https://stenciljs.com/docs/config#globalscript}
+ * @see [Stencil's globalScript](https://stenciljs.com/docs/config#globalscript).
  */
 export default function (): void {
   if (isBrowser()) {

diff --git a/vitest.workspace.ts b/vitest.workspace.ts
@@ -5,8 +5,6 @@ import { workspaces } from "./package.json";
  * This helps Vitest VS Code extensions discover all vite config files in the
  * monorepo in a more performant way
  *
- * @see https://vitest.dev/guide/workspace.html
+ * @see [Vitest Workspace](https://vitest.dev/guide/workspace.html)
  */
-export default defineWorkspace(
-  workspaces.map((workspace) => `${workspace}/vite.config.ts`),
-);
+export default defineWorkspace(workspaces.map((workspace) => `${workspace}/vite.config.ts`));