Use JSDoc linkcode annotation for documentation hyperlinks (#2370)

* Replace [[`symbol`]] doc links with linkcode JSDoc/TSDoc annotation which has IDE support.

Co-authored-by: Andrew Jakubowicz <ajakubowicz@google.com>

.changeset/wise-taxis-refuse.md

@@ -0,0 +1,7 @@
+---
+'lit-element': patch
+'@lit/reactive-element': patch
+---
+
+Replace square bracket links with the `linkcode` JSDoc tag.
+Editors will create a jump to definition hyperlink for the linkcode tag if the identifier is in scope.

packages/lit-element/src/lit-element.ts

@@ -5,15 +5,15 @@
  */
 
 /**
- * The main LitElement module, which defines the [[`LitElement`]] base class and
- * related APIs.
+ * The main LitElement module, which defines the {@linkcode LitElement} base
+ * class and related APIs.
  *
  *  LitElement components can define a template and a set of observed
  * properties. Changing an observed property triggers a re-render of the
  * element.
  *
- *  Import [[`LitElement`]] and [[`html`]] from this module to create a
- * component:
+ *  Import {@linkcode LitElement} and {@linkcode html} from this module to
+ * create a component:
  *
  *  ```js
  * import {LitElement, html} from 'lit-element';
@@ -40,9 +40,9 @@
  * customElements.define('my-element', MyElement);
  * ```
  *
- * `LitElement` extends [[`ReactiveElement`]] and adds lit-html templating.
- * The `ReactiveElement` class is provided for users that want to build
- * their own custom element base classes that don't use lit-html.
+ * `LitElement` extends {@linkcode ReactiveElement} and adds lit-html
+ * templating. The `ReactiveElement` class is provided for users that want to
+ * build their own custom element base classes that don't use lit-html.
  *
  * @packageDocumentation
  */
@@ -81,7 +81,8 @@ if (DEV_MODE) {
  *
  * To define a component, subclass `LitElement` and implement a
  * `render` method to provide the component's template. Define properties
- * using the [[`properties`]] property or the [[`property`]] decorator.
+ * using the {@linkcode LitElement.properties properties} property or the
+ * {@linkcode property} decorator.
  */
 export class LitElement extends ReactiveElement {
   /**

packages/reactive-element/src/css-tag.ts

@@ -92,7 +92,7 @@ const textFromCSSResult = (value: CSSResultGroup | number) => {
 };
 
 /**
- * Wrap a value for interpolation in a [[`css`]] tagged template literal.
+ * Wrap a value for interpolation in a {@linkcode css} tagged template literal.
  *
  * This is unsafe because untrusted CSS text can be used to phone home
  * or exfiltrate data to an attacker controlled site. Take care to only use
@@ -106,11 +106,11 @@ export const unsafeCSS = (value: unknown) =>
 
 /**
  * A template literal tag which can be used with LitElement's
- * [[LitElement.styles | `styles`]] property to set element styles.
+ * {@linkcode LitElement.styles} property to set element styles.
  *
  * For security reasons, only literal string values and number may be used in
- * embedded expressions. To incorporate non-literal values [[`unsafeCSS`]] may
- * be used inside an expression.
+ * embedded expressions. To incorporate non-literal values {@linkcode unsafeCSS}
+ * may be used inside an expression.
  */
 export const css = (
   strings: TemplateStringsArray,

packages/reactive-element/src/decorators/property.ts

@@ -74,25 +74,25 @@ const legacyProperty = (
 /**
  * A property decorator which creates a reactive property that reflects a
  * corresponding attribute value. When a decorated property is set
- * the element will update and render. A [[`PropertyDeclaration`]] may
+ * the element will update and render. A {@linkcode PropertyDeclaration} may
  * optionally be supplied to configure property features.
  *
  * This decorator should only be used for public fields. As public fields,
  * properties should be considered as primarily settable by element users,
  * either via attribute or the property itself.
  *
  * Generally, properties that are changed by the element should be private or
- * protected fields and should use the [[`state`]] decorator.
+ * protected fields and should use the {@linkcode state} decorator.
  *
  * However, sometimes element code does need to set a public property. This
  * should typically only be done in response to user interaction, and an event
  * should be fired informing the user; for example, a checkbox sets its
  * `checked` property when clicked and fires a `changed` event. Mutating public
  * properties should typically not be done for non-primitive (object or array)
  * properties. In other cases when an element needs to manage state, a private
- * property decorated via the [[`state`]] decorator should be used. When needed,
- * state properties can be initialized via public properties to facilitate
- * complex interactions.
+ * property decorated via the {@linkcode state} decorator should be used. When
+ * needed, state properties can be initialized via public properties to
+ * facilitate complex interactions.
  *
  * ```ts
  * class MyElement {

packages/reactive-element/src/decorators/query-assigned-elements.ts

@@ -31,8 +31,8 @@ const slotAssignedElements =
           );
 
 /**
- * Options for the [[`queryAssignedElements`]] decorator. Extends the options
- * that can be passed into
+ * Options for the {@linkcode queryAssignedElements} decorator. Extends the
+ * options that can be passed into
  * [HTMLSlotElement.assignedElements](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedElements).
  */
 export interface QueryAssignedElementsOptions
@@ -50,7 +50,7 @@ export interface QueryAssignedElementsOptions
  * way to use
  * [`slot.assignedElements`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedElements).
  *
- * Can be passed an optional [[`QueryAssignedElementsOptions`]] object.
+ * Can be passed an optional {@linkcode QueryAssignedElementsOptions} object.
  *
  * Example usage:
  * ```ts

packages/reactive-element/src/decorators/query-assigned-nodes.ts

@@ -17,9 +17,8 @@ import {queryAssignedElements} from './query-assigned-elements.js';
 import type {ReactiveElement} from '../reactive-element.js';
 
 /**
- * Options for the [[`queryAssignedNodes`]] decorator. Extends the options that
- * can be passed into
- * [HTMLSlotElement.assignedNodes](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedNodes).
+ * Options for the {@linkcode queryAssignedNodes} decorator. Extends the options
+ * that can be passed into [HTMLSlotElement.assignedNodes](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedNodes).
  */
 export interface QueryAssignedNodesOptions extends AssignedNodesOptions {
   /**
@@ -36,7 +35,7 @@ type TSDecoratorReturnType = void | any;
  * A property decorator that converts a class property into a getter that
  * returns the `assignedNodes` of the given `slot`.
  *
- * Can be passed an optional [[`QueryAssignedNodesOptions`]] object.
+ * Can be passed an optional {@linkcode QueryAssignedNodesOptions} object.
  *
  * Example usage:
  * ```ts

packages/reactive-element/src/reactive-element.ts

@@ -6,7 +6,7 @@
 
 /**
  * Use this module if you want to create your own base class extending
- * [[ReactiveElement]].
+ * {@link ReactiveElement}.
  * @packageDocumentation
  */
 
@@ -468,7 +468,7 @@ export abstract class ReactiveElement
 
   /**
    * Array of styles to apply to the element. The styles should be defined
-   * using the [[`css`]] tag function, via constructible stylesheets, or
+   * using the {@linkcode css} tag function, via constructible stylesheets, or
    * imported from native CSS module scripts.
    *
    * Note on Content Security Policy:
@@ -524,10 +524,10 @@ export abstract class ReactiveElement
 
   /**
    * Creates a property accessor on the element prototype if one does not exist
-   * and stores a `PropertyDeclaration` for the property with the given options.
-   * The property setter calls the property's `hasChanged` property option
-   * or uses a strict identity check to determine whether or not to request
-   * an update.
+   * and stores a {@linkcode PropertyDeclaration} for the property with the
+   * given options. The property setter calls the property's `hasChanged`
+   * property option or uses a strict identity check to determine whether or not
+   * to request an update.
    *
    * This method may be overridden to customize properties; however,
    * when doing so, it's important to call `super.createProperty` to ensure
@@ -645,7 +645,8 @@ export abstract class ReactiveElement
    * `createProperty(...)`.
    *
    * Note, this method should be considered "final" and not overridden. To
-   * customize the options for a given property, override [[`createProperty`]].
+   * customize the options for a given property, override
+   * {@linkcode createProperty}.
    *
    * @nocollapse
    * @final