Document describeCss, tweak docs of describeText…
diff --git a/packages/dom/src/css.ts b/packages/dom/src/css.ts
index 746486a..1026004 100644
--- a/packages/dom/src/css.ts
+++ b/packages/dom/src/css.ts
@@ -75,6 +75,27 @@
};
}
+/**
+ * Returns a {@link CssSelector} that unambiguously describes the given
+ * element, within the given scope.
+ *
+ * @example
+ * ```
+ * const target = document.getElementById('targetelement').firstElementChild;
+ * const selector = await describeCss(target);
+ * console.log(selector);
+ * // {
+ * // type: 'CssSelector',
+ * // value: '#targetelement > :nth-child(1)'
+ * // }
+ * ```
+ *
+ * @param element - The element that the selector should describe.
+ * @param scope - The node that serves as the ‘document’ for purposes of finding
+ * a unique selector. Defaults to span the full Document that contains the
+ * `element`.
+ * @returns The selector unambiguously describing `element` within `scope`.
+ */
export async function describeCss(
element: HTMLElement,
scope: Node = element.ownerDocument,
diff --git a/packages/dom/src/text-position/describe.ts b/packages/dom/src/text-position/describe.ts
index fd96680..bd2f42b 100644
--- a/packages/dom/src/text-position/describe.ts
+++ b/packages/dom/src/text-position/describe.ts
@@ -24,8 +24,8 @@
import { TextNodeChunker } from '../text-node-chunker';
/**
- * Returns a {@link TextPositionSelector} that points
- * at the target text within the given scope.
+ * Returns a {@link TextPositionSelector} that points at the target text within
+ * the given scope.
*
* When no scope is given, the position is described relative to the document
* as a whole. Note this means all the characters in all Text nodes are counted
@@ -50,7 +50,7 @@
* | Range} that serves as the ‘document’ for purposes of finding occurrences
* and determining prefix and suffix. Defaults to span the full Document
* containing the range.
- * @returns The selector describing the `range` relative to `scope`
+ * @returns The selector describing `range` within `scope`.
*
* @public
*/
diff --git a/packages/dom/src/text-quote/describe.ts b/packages/dom/src/text-quote/describe.ts
index 642070d..8eca8bf 100644
--- a/packages/dom/src/text-quote/describe.ts
+++ b/packages/dom/src/text-quote/describe.ts
@@ -27,8 +27,8 @@
import { TextNodeChunker } from '../text-node-chunker';
/**
- * Create a {@link TextQuoteSelector} that
- * unambiguously describes the given range.
+ * Returns a {@link TextQuoteSelector} that unambiguously describes the given
+ * range of text, within the given scope.
*
* The selector will contain the *exact* target quote, and in case this quote
* appears multiple times in the text, sufficient context around the quote will
@@ -57,7 +57,7 @@
* and determining prefix and suffix. Defaults to span the full Document
* containing the range.
* @param options - Options to fine-tune the function’s behaviour.
- * @returns The selector unambiguously describing the `range` in `scope`.
+ * @returns The selector unambiguously describing `range` within `scope`.
*
* @public
*/
