You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@annotator.apache.org by ge...@apache.org on 2021/04/06 08:30:06 UTC
[incubator-annotator] 03/03: Turn tsdoc into typedoc
This is an automated email from the ASF dual-hosted git repository.
gerben pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-annotator.git
commit 552b6ca9618704d639380563f5a79428b978472b
Author: Gerben <ge...@treora.com>
AuthorDate: Mon Apr 5 20:59:28 2021 +0200
Turn tsdoc into typedoc
---
packages/dom/src/css.ts | 9 ++++-----
packages/dom/src/highlight-range.ts | 1 -
packages/dom/src/normalize-range.ts | 1 -
packages/dom/src/range/match.ts | 6 +++---
packages/dom/src/text-position/describe.ts | 2 +-
packages/dom/src/text-position/match.ts | 9 ++++-----
packages/dom/src/text-quote/describe.ts | 3 +--
packages/dom/src/text-quote/match.ts | 7 +++----
packages/selector/src/index.ts | 1 -
packages/selector/src/text/chunker.ts | 21 +++++++--------------
packages/selector/src/text/code-point-seeker.ts | 4 +---
.../selector/src/text/describe-text-position.ts | 2 +-
packages/selector/src/text/describe-text-quote.ts | 3 +--
packages/selector/src/text/match-text-position.ts | 3 +--
packages/selector/src/text/match-text-quote.ts | 3 +--
packages/selector/src/text/seeker.ts | 9 +++------
packages/selector/src/types.ts | 1 -
17 files changed, 31 insertions(+), 54 deletions(-)
diff --git a/packages/dom/src/css.ts b/packages/dom/src/css.ts
index f6782f5..c8c0db5 100644
--- a/packages/dom/src/css.ts
+++ b/packages/dom/src/css.ts
@@ -23,9 +23,8 @@ import { ownerDocument } from './owner-document';
/**
* Find the elements corresponding to the given {@link
- * @apache-annotator/selector#CssSelector}.
+ * CssSelector}.
*
- * @remarks
* The given CssSelector returns all elements within `scope` that it matches.
* However, the selector is evaluated relative to the Document as a whole.
* *(XXX is this intentional, a mistake, or compromise?)*
@@ -39,11 +38,11 @@ import { ownerDocument } from './owner-document';
* Each matching element is returned as a {@link https://developer.mozilla.org/en-US/docs/Web/API/Range
* | Range} surrounding that element. This in order to make its output reusable
* as the scope for any subsequents selectors that {@link
- * @apache-annotator/selector#Selector.refinedBy | refine} this CssSelector.
+ * Selector.refinedBy | refine} this CssSelector.
*
- * @param selector - The {@link @apache-annotator/selector#CssSelector} to be
+ * @param selector - The {@link CssSelector} to be
* anchored
- * @returns A {@link @apache-annotator/selector#Matcher} function that applies
+ * @returns A {@link Matcher} function that applies
* `selector` to a given {@link https://developer.mozilla.org/en-US/docs/Web/API/Range
* | Range}
*
diff --git a/packages/dom/src/highlight-range.ts b/packages/dom/src/highlight-range.ts
index 18684c5..93ff390 100644
--- a/packages/dom/src/highlight-range.ts
+++ b/packages/dom/src/highlight-range.ts
@@ -23,7 +23,6 @@ import { ownerDocument } from './owner-document';
/**
* Wrap each text node in a given DOM Range with a `<mark>` or other element.
*
- * @remarks
* If the Range start and/or ends within a Text node, that node will be split
* in order to only wrap the contained part in the mark element.
*
diff --git a/packages/dom/src/normalize-range.ts b/packages/dom/src/normalize-range.ts
index 84bbda2..0b41899 100644
--- a/packages/dom/src/normalize-range.ts
+++ b/packages/dom/src/normalize-range.ts
@@ -50,7 +50,6 @@ export interface TextRange extends Range {
* Normalise a {@link https://developer.mozilla.org/en-US/docs/Web/API/Range |
* Range} such that ranges spanning the same text become exact equals.
*
- * @remarks
* *Note: in this context ‘text’ means any characters, including whitespace.*
* Normalises a range such that both its start and end are text nodes, and that
diff --git a/packages/dom/src/range/match.ts b/packages/dom/src/range/match.ts
index dd4b982..b733e06 100644
--- a/packages/dom/src/range/match.ts
+++ b/packages/dom/src/range/match.ts
@@ -28,7 +28,7 @@ import { cartesian } from './cartesian';
/**
* Find the range(s) corresponding to the given {@link
- * @apache-annotator/selector#RangeSelector}.
+ * RangeSelector}.
*
* As a RangeSelector itself nests two further selectors, one needs to pass a
* `createMatcher` function that will be used to process those nested selectors.
@@ -45,7 +45,7 @@ import { cartesian } from './cartesian';
* matches for RangeSelectors)*
*
* @example
- * By using a matcher for {@link @apache-annotator/selector#TextQuoteSelector}s, one
+ * By using a matcher for {@link TextQuoteSelector}s, one
* could create a matcher for text quotes with ellipsis to select a phrase
* “ipsum … amet,”:
* ```
@@ -87,7 +87,7 @@ import { cartesian } from './cartesian';
*
* @param createMatcher - The function used to process nested selectors.
* @returns A function that, given a RangeSelector, creates a {@link
- * @apache-annotator/selector#Matcher} function that applies it to a given {@link https://developer.mozilla.org/en-US/docs/Web/API/Range
+ * Matcher} function that applies it to a given {@link https://developer.mozilla.org/en-US/docs/Web/API/Range
* | Range}
*
* @public
diff --git a/packages/dom/src/text-position/describe.ts b/packages/dom/src/text-position/describe.ts
index ae06a94..fd96680 100644
--- a/packages/dom/src/text-position/describe.ts
+++ b/packages/dom/src/text-position/describe.ts
@@ -24,7 +24,7 @@ import { ownerDocument } from '../owner-document';
import { TextNodeChunker } from '../text-node-chunker';
/**
- * Returns a {@link @apache-annotator/selector#TextPositionSelector} that points
+ * 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
diff --git a/packages/dom/src/text-position/match.ts b/packages/dom/src/text-position/match.ts
index f8d0917..089def8 100644
--- a/packages/dom/src/text-position/match.ts
+++ b/packages/dom/src/text-position/match.ts
@@ -24,9 +24,8 @@ import { TextNodeChunker } from '../text-node-chunker';
/**
* Find the range of text corresponding to the given {@link
- * @apache-annotator/selector#TextPositionSelector}.
+ * TextPositionSelector}.
*
- * @remarks
* The start and end positions are measured relative to the first text character
* in the given scope.
*
@@ -34,7 +33,7 @@ import { TextNodeChunker } from '../text-node-chunker';
*
* Its end result is an (async) generator producing a single {@link https://developer.mozilla.org/en-US/docs/Web/API/Range
* | Range} to represent the match. (unlike a {@link
- * @apache-annotator/selector#TextQuoteSelector}, a TextPositionSelector cannot have
+ * TextQuoteSelector}, a TextPositionSelector cannot have
* multiple matches).
*
* @example
@@ -52,9 +51,9 @@ import { TextNodeChunker } from '../text-node-chunker';
* // endOffset: 98, … }
* ```
*
- * @param selector - The {@link @apache-annotator/selector#TextPositionSelector}
+ * @param selector - The {@link TextPositionSelector}
* to be anchored
- * @returns A {@link @apache-annotator/selector#Matcher} function that applies
+ * @returns A {@link Matcher} function that applies
* `selector` to a given {@link https://developer.mozilla.org/en-US/docs/Web/API/Range
* | Range}
*
diff --git a/packages/dom/src/text-quote/describe.ts b/packages/dom/src/text-quote/describe.ts
index 3958633..642070d 100644
--- a/packages/dom/src/text-quote/describe.ts
+++ b/packages/dom/src/text-quote/describe.ts
@@ -27,10 +27,9 @@ import { ownerDocument } from '../owner-document';
import { TextNodeChunker } from '../text-node-chunker';
/**
- * Create a {@link @apache-annotator/selector#TextQuoteSelector} that
+ * Create a {@link TextQuoteSelector} that
* unambiguously describes the given range.
*
- * @remarks
* 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
* be included in the selector’s *prefix* and *suffix* attributes to
diff --git a/packages/dom/src/text-quote/match.ts b/packages/dom/src/text-quote/match.ts
index 0f263e7..a923586 100644
--- a/packages/dom/src/text-quote/match.ts
+++ b/packages/dom/src/text-quote/match.ts
@@ -24,9 +24,8 @@ import { TextNodeChunker, EmptyScopeError } from '../text-node-chunker';
/**
* Find occurrences in a text matching the given {@link
- * @apache-annotator/selector#TextQuoteSelector}.
+ * TextQuoteSelector}.
*
- * @remarks
* This performs an exact search for the selector’s quote (including prefix and
* suffix) within the text contained in the given scope (a {@link
* https://developer.mozilla.org/en-US/docs/Web/API/Range | Range}).
@@ -59,9 +58,9 @@ import { TextNodeChunker, EmptyScopeError } from '../text-node-chunker';
* // endOffset: 637, … }
* ```
*
- * @param selector - The {@link @apache-annotator/selector#TextQuoteSelector}
+ * @param selector - The {@link TextQuoteSelector}
* to be anchored
- * @returns a {@link @apache-annotator/selector#Matcher} function that applies
+ * @returns a {@link Matcher} function that applies
* `selector` to a given {@link https://developer.mozilla.org/en-US/docs/Web/API/Range
* | Range}
*
diff --git a/packages/selector/src/index.ts b/packages/selector/src/index.ts
index d0a6607..e0a5e48 100644
--- a/packages/selector/src/index.ts
+++ b/packages/selector/src/index.ts
@@ -32,7 +32,6 @@ export * from './text';
/**
* Wrap a matcher creation function so that it supports refinement of selection.
*
- * @remarks
* See {@link https://www.w3.org/TR/2017/REC-annotation-model-20170223/#refinement-of-selection
* | §4.2.9 Refinement of Selection} in the Web Annotation Data Model.
*
diff --git a/packages/selector/src/text/chunker.ts b/packages/selector/src/text/chunker.ts
index 88fac13..4d959d2 100644
--- a/packages/selector/src/text/chunker.ts
+++ b/packages/selector/src/text/chunker.ts
@@ -21,7 +21,6 @@
/**
* Represents a piece of text in any kind of ‘file’.
*
- * @remarks
* Its purpose is to enable generic algorithms to deal with text content of any
* type of ‘file’ that consists of many pieces of text (e.g. a DOM, PDF, …).
* Each Chunk represents one piece of text ({@link Chunk.data}). An object
@@ -43,10 +42,9 @@ export interface Chunk<TData> {
/**
* Test two {@link Chunk}s for equality.
*
- * @remarks
* Equality here means that both represent the same piece of text (i.e. at the
* same position) in the file. It compares using the custom {@link Chunk.equals}
- * method either chunk defines one, and falls back to checking the objects’
+ * method if either chunk defines one, and falls back to checking the objects’
* identity (i.e. `chunk1 === chunk2`).
*
* @public
@@ -60,7 +58,6 @@ export function chunkEquals(chunk1: Chunk<any>, chunk2: Chunk<any>): boolean {
/**
* Points at a range of characters between two points inside {@link Chunk}s.
*
- * @remarks
* Analogous to the DOM’s ({@link https://developer.mozilla.org/en-US/docs/Web/API/AbstractRange
* | Abstract}){@link https://developer.mozilla.org/en-US/docs/Web/API/Range |
* Range}. Each index expresses an offset inside the value of the corresponding
@@ -79,11 +76,10 @@ export interface ChunkRange<TChunk extends Chunk<any>> {
/**
* Test two {@link ChunkRange}s for equality.
*
- * @remarks
* Equality here means equality of each of their four properties (i.e.
- * {@link ChunkRange.startChunk}, {@link ChunkRange.startIndex},
- * {@link ChunkRange.endChunk}, and {@link ChunkRange.endIndex}).
- * For the `startChunk` and `endChunk`, this function uses the custom
+ * {@link startChunk}, {@link startIndex},
+ * {@link endChunk}, and {@link endIndex}).
+ * For the `startChunk`s and `endChunk`s, this function uses the custom
* {@link Chunk.equals} method if defined.
*
* Note that if the start/end of one range points at the end of a chunk, and the
@@ -111,7 +107,6 @@ export function chunkRangeEquals(
* Presents the pieces of text contained in some underlying ‘file’ as a sequence
* of {@link Chunk}s.
*
- * @remarks
* Rather than presenting a list of all pieces, the `Chunker` provides methods
* to walk through the file piece by piece. This permits implementations to read
* and convert the file to `Chunk`s lazily.
@@ -127,30 +122,28 @@ export interface Chunker<TChunk extends Chunk<any>> {
/**
* The chunk currently being pointed at.
*
- * @remarks
* Initially, this should normally be the first chunk in the file.
*/
readonly currentChunk: TChunk;
/**
- * Point {@link Chunker.currentChunk} at the chunk following it, and return that chunk.
+ * Point {@link currentChunk} at the chunk following it, and return that chunk.
* If there are no chunks following it, keep `currentChunk` unchanged and
* return null.
*/
nextChunk(): TChunk | null;
/**
- * Point {@link Chunker.currentChunk} at the chunk preceding it, and return that chunk.
+ * Point {@link currentChunk} at the chunk preceding it, and return that chunk.
* If there are no chunks preceding it, keep `currentChunk` unchanged and
* return null.
*/
previousChunk(): TChunk | null;
/**
- * Test if a given `chunk` is before the {@link Chunker.currentChunk|current
+ * Test if a given `chunk` is before the {@link currentChunk|current
* chunk}.
*
- * @remarks
* Returns true if `chunk` is before `this.currentChunk`, false otherwise
* (i.e. if `chunk` follows it or is the current chunk).
*
diff --git a/packages/selector/src/text/code-point-seeker.ts b/packages/selector/src/text/code-point-seeker.ts
index 9e31def..5751f1e 100644
--- a/packages/selector/src/text/code-point-seeker.ts
+++ b/packages/selector/src/text/code-point-seeker.ts
@@ -24,15 +24,13 @@ import type { Seeker } from './seeker';
/**
* Seeks through text counting Unicode *code points* instead of *code units*.
*
- * @remarks
* Javascript characters correspond to 16 bits *code units*, hence two such
* ‘characters’ might together constitute a single Unicode character (i.e. a
* *code point*). The {@link CodePointSeeker} allows to ignore this
* variable-length encoding, by counting code points instead.
*
* It is made to wrap a {@link Seeker} that counts code units (presumably a
- * {@link TextSeeker}), which must be passed to its {@link this:constructor |
- * constructor}.
+ * {@link TextSeeker}), which must be passed to its {@link constructor}.
*
* When reading from the `CodePointSeeker`, the returned values is not a string
* but an array of strings, each containing one code point (thus each having a
diff --git a/packages/selector/src/text/describe-text-position.ts b/packages/selector/src/text/describe-text-position.ts
index a026380..a5a7cd8 100644
--- a/packages/selector/src/text/describe-text-position.ts
+++ b/packages/selector/src/text/describe-text-position.ts
@@ -31,7 +31,7 @@ import { TextSeeker } from './seeker';
* generic {@link Chunker} to represent the text, and a {@link ChunkRange} to
* represent the target.
*
- * See {@link @apache-annotator/dom#describeTextPosition} for a wrapper around
+ * See {@link dom.describeTextPosition} for a wrapper around
* this implementation which applies it to the text of an HTML DOM.
*
* @param target - The range of characters that the selector should describe
diff --git a/packages/selector/src/text/describe-text-quote.ts b/packages/selector/src/text/describe-text-quote.ts
index 3b129fb..54b5e01 100644
--- a/packages/selector/src/text/describe-text-quote.ts
+++ b/packages/selector/src/text/describe-text-quote.ts
@@ -52,7 +52,6 @@ export interface DescribeTextQuoteOptions {
* Returns a {@link TextQuoteSelector} that points at the target quote in the
* given text.
*
- * @remarks
* The selector will contain the exact target quote. In case this quote appears
* multiple times in the text, sufficient context around the quote will be
* included in the selector’s `prefix` and `suffix` attributes to disambiguate.
@@ -64,7 +63,7 @@ export interface DescribeTextQuoteOptions {
* generic {@link Chunker} to represent the text, and a {@link ChunkRange} to
* represent the target.
*
- * See {@link @apache-annotator/dom#describeTextQuote} for a wrapper around this
+ * See {@link dom.describeTextQuote} for a wrapper around this
* implementation which applies it to the text of an HTML DOM.
*
* @param target - The range of characters that the selector should describe
diff --git a/packages/selector/src/text/match-text-position.ts b/packages/selector/src/text/match-text-position.ts
index b6bb3e9..6f2f8be 100644
--- a/packages/selector/src/text/match-text-position.ts
+++ b/packages/selector/src/text/match-text-position.ts
@@ -26,13 +26,12 @@ import { TextSeeker } from './seeker';
/**
* Find the range of text corresponding to the given {@link TextPositionSelector}.
*
- * @remarks
* This is an abstract implementation of the function’s logic, which expects a
* generic {@link Chunker} to represent the text, and returns an (async)
* generator producing a single {@link ChunkRange} to represent the match.
* (unlike e.g. TextQuoteSelector, it cannot result in multiple matches).
*
- * See {@link @apache-annotator/dom#createTextPositionSelectorMatcher} for a
+ * See {@link dom.createTextPositionSelectorMatcher} for a
* wrapper around this implementation which applies it to the text of an HTML
* DOM.
*
diff --git a/packages/selector/src/text/match-text-quote.ts b/packages/selector/src/text/match-text-quote.ts
index d3712bb..0531369 100644
--- a/packages/selector/src/text/match-text-quote.ts
+++ b/packages/selector/src/text/match-text-quote.ts
@@ -24,7 +24,6 @@ import type { Chunk, Chunker, ChunkRange } from './chunker';
/**
* Find occurrences in a text matching the given {@link TextQuoteSelector}.
*
- * @remarks
* This performs an exact search the selector’s quote (including prefix and
* suffix) within the given text.
*
@@ -35,7 +34,7 @@ import type { Chunk, Chunker, ChunkRange } from './chunker';
* generic {@link Chunker} to represent the text, and returns an (async)
* generator of {@link ChunkRange}s to represent the matches.
*
- * See {@link @apache-annotator/dom#createTextQuoteSelectorMatcher} for a
+ * See {@link dom.createTextQuoteSelectorMatcher} for a
* wrapper around this implementation which applies it to the text of an HTML
* DOM.
*
diff --git a/packages/selector/src/text/seeker.ts b/packages/selector/src/text/seeker.ts
index 53fdb49..b8246c6 100644
--- a/packages/selector/src/text/seeker.ts
+++ b/packages/selector/src/text/seeker.ts
@@ -27,7 +27,6 @@ const E_END = 'Iterator exhausted before seek ended.';
* Abstraction to seek (jump) or read to a position inside a ‘file’ consisting of a
* sequence of data chunks.
*
- * @remarks
* This interface is a combination of three interfaces in one: for seeking to a
* relative position, an absolute position, or a specific chunk. These three are
* defined separately for clarity and flexibility, but normally used together.
@@ -69,7 +68,7 @@ export interface RelativeSeeker<TData extends Iterable<any> = string> {
/**
* Read forward or backward by a number of characters.
*
- * @remarks Equal to {@link seekBy}, but returning the characters passed.
+ * Equal to {@link seekBy}, but returning the characters passed.
*
* @param length - The number of characters to read. A negative number moves
* backwards in the file.
@@ -110,7 +109,7 @@ export interface AbsoluteSeeker<TData extends Iterable<any> = string> {
* Read forward or backward from the current to the given position in the
* file, returning the characters that have been passed.
*
- * @remarks Equal to {@link seekTo}, but returning the characters passed.
+ * Equal to {@link seekTo}, but returning the characters passed.
*
* @param target - The position to end up at.
* @param roundUp - If true, then, after reading to the target position, read
@@ -140,7 +139,6 @@ export interface ChunkSeeker<
/**
* The chunk containing the current position.
*
- * @remarks
* When the position falls at the edge between two chunks, `currentChunk` is
* always the later one (thus {@link offsetInChunk} would be zero). Note that
* an empty chunk (for which position zero is at both its edges) can
@@ -168,7 +166,7 @@ export interface ChunkSeeker<
/**
* Read to the start of a given chunk, or to an offset relative to that.
*
- * @remarks Equal to {@link seekToChunk}, but returning the characters passed.
+ * Equal to {@link seekToChunk}, but returning the characters passed.
*
* @param chunk - The chunk of the file to move to.
* @param offset - The offset to move to, relative to the start of `chunk`.
@@ -184,7 +182,6 @@ export interface ChunkSeeker<
* A TextSeeker is constructed around a {@link Chunker}, to let it be treated as
* a continuous sequence of characters.
*
- * @remarks
* Seeking to a given numeric position will cause a `TextSeeker` to pull chunks
* from the underlying `Chunker`, counting their lengths until the requested
* position is reached. `Chunks` are not stored but simply read again when
diff --git a/packages/selector/src/types.ts b/packages/selector/src/types.ts
index fa367ee..fd59dfb 100644
--- a/packages/selector/src/types.ts
+++ b/packages/selector/src/types.ts
@@ -30,7 +30,6 @@ export interface Selector {
/**
* A Selector can be refined by another Selector.
*
- * @remarks
* See {@link https://www.w3.org/TR/2017/REC-annotation-model-20170223/#refinement-of-selection
* | §4.2.9 Refinement of Selection} in the Web Annotation Data Model.
*