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 <[email protected]> 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. *
