Merge 825239a into e1c8826

lit · Dec 14, 2021 · 1f3af4e · 1f3af4e
2 parents e1c8826 + 825239a
commit 1f3af4e
Show file tree

Hide file tree

Showing 3 changed files with 22 additions and 17 deletions.
diff --git a/.changeset/brave-planes-juggle.md b/.changeset/brave-planes-juggle.md
@@ -0,0 +1,5 @@
+---
+'@lit/reactive-element': patch
+---
+
+Update `@queryAssignedNodes` and `@queryAssignedElements` documentation for better lit.dev API generation.
diff --git a/packages/reactive-element/src/decorators/query-assigned-elements.ts b/packages/reactive-element/src/decorators/query-assigned-elements.ts
@@ -16,10 +16,16 @@ import {decorateProperty} from './base.js';
 import type {ReactiveElement} from '../reactive-element.js';
 import type {QueryAssignedNodesOptions} from './query-assigned-nodes.js';
 
+/**
+ * Options for the [[`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
   extends QueryAssignedNodesOptions {
   /**
-   * CSS selector used to filter the elements returned.
+   * CSS selector used to filter the elements returned. For example, a selector
+   * of `".item"` will only include elements with the `item` class.
    */
   selector?: string;
 }
@@ -30,6 +36,8 @@ 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.
+ *
  * Example usage:
  * ```ts
  * class MyElement {
@@ -49,15 +57,6 @@ export interface QueryAssignedElementsOptions
  *
  * Note, the type of this property should be annotated as `Array<HTMLElement>`.
  *
- * @param options Object that sets options for nodes to be returned. See
- *     [MDN parameters section](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedElements#parameters)
- *     for available options. Also accepts two more optional properties,
- *     `slot` and `selector`.
- * @param options.slot Name of the slot. Undefined or empty string for the
- *     default slot.
- * @param options.selector Element results are filtered such that they match the
- *     given CSS selector.
- *
  * @category Decorator
  */
 export function queryAssignedElements(options?: QueryAssignedElementsOptions) {

diff --git a/packages/reactive-element/src/decorators/query-assigned-nodes.ts b/packages/reactive-element/src/decorators/query-assigned-nodes.ts
@@ -15,9 +15,14 @@ import {decorateProperty} from './base.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).
+ */
 export interface QueryAssignedNodesOptions extends AssignedNodesOptions {
   /**
-   * Name of the slot. Leave empty for the default slot.
+   * Name of the slot to query. Leave empty for the default slot.
    */
   slot?: string;
 }
@@ -30,6 +35,8 @@ 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.
+ *
  * Example usage:
  * ```ts
  * class MyElement {
@@ -46,12 +53,6 @@ type TSDecoratorReturnType = void | any;
  *
  * Note the type of this property should be annotated as `Array<Node>`.
  *
- * @param options Object that sets options for nodes to be returned. See
- *     [MDN parameters section](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedNodes#parameters)
- *     for available options.
- * @param options.slot Name of the slot. Undefined or empty string for the
- *     default slot.
- *
  * @category Decorator
  */
 export function queryAssignedNodes(