@g3nomaly/analyze 0.1.0 → 0.1.1

package/dist/scanner/specs.d.ts

@@ -5,18 +5,20 @@ import { type Reporter } from './reporter';
 import { type JsonObject } from './schema/describe';
 import type { JsonSchemaPlanner } from './schema/planner';
 /**
- * A **spec** is a JSON or YAML file that describes data or an API in a
+ * Kind of a spec: a JSON or YAML file that describes data or an API in a
  * standard format: an OpenAPI document or a JSON Schema.
  */
 export type SpecKind = 'openapi' | 'json-schema';
 /**
  * Tells what kind of spec a parsed file is.
  *
+ * @param path - Path of the file, whose name is checked against the schema names.
+ * @param document - The parsed file.
  * @returns `openapi` for a document with an `openapi` version 3 and paths, components or webhooks. `json-schema` for a document whose `$schema` names JSON Schema, or that is named like a schema and uses its keywords. `null` for anything else.
  */
 export declare function specKind(path: string, document: JsonObject): SpecKind | null;
 /**
- * Adds the specs among the JSON and YAML files of a scan to the graph.
+ * @brief Adds the specs among the JSON and YAML files of a scan to the graph.
  *
  * Used by `DocPlanner` and `SkillPlanner` for every JSON or YAML file, before
  * they add the file as plain text. The file is parsed once here, and goes to
@@ -29,6 +31,8 @@ export declare class SpecPlanner {
     /**
      * Keeps the planner of each spec kind.
      *
+     * @param openapi - Plans OpenAPI documents.
+     * @param schemas - Plans JSON Schemas.
      * @param reporter - Receives files that cannot be read.
      */
     constructor(openapi: OpenApiPlanner, schemas: JsonSchemaPlanner, reporter?: Reporter);
@@ -37,6 +41,7 @@ export declare class SpecPlanner {
     /**
      * Reads one file and adds it when it is a spec.
      *
+     * @param file - The file to read, with its root and path.
      * @param parent - Gives the folder or skill the file is in. Called only for a spec, so a folder with nothing else in it is not added.
      * @returns The node of the file, or `null` when the file is no spec or cannot be parsed.
      */
@@ -44,6 +49,7 @@ export declare class SpecPlanner {
     /**
      * Parses a file.
      *
+     * @param file - The file to read, with its root and path.
      * @returns The parsed object, or `null` for a file that is too large, holds no object or is not valid.
      */
     private read;

package/dist/scanner/sql/catalog.d.ts

@@ -6,23 +6,32 @@ import type { ProseResolvers } from '../markdown/links';
 import type { MarkdownRenderer } from '../markdown/renderer';
 import type { ParsedQuery } from './query';
 import { type TableRegistry } from './registry';
-/** One SQL file of a catalog with the entries it holds. */
+/**
+ * One SQL file of a catalog with the entries it holds.
+ *
+ * @property file - The SQL file, with its root and paths.
+ * @property queries - Entries from `parseQueryFile`. Not empty.
+ */
 export interface CatalogFile {
     readonly file: SourceFile;
-    /** From `parseQueryFile`. Not empty. */
     readonly queries: readonly ParsedQuery[];
 }
-/** Where a catalog goes in the tree and what it is called. */
+/**
+ * Where a catalog goes in the tree and what it is called.
+ *
+ * @property parent - Folder or section the catalog goes in.
+ * @property name - Name the catalog is shown under.
+ * @property slug - Segment of the route of the catalog, when it is not the name.
+ * @property path - Path of the directory of the catalog, as the site shows it.
+ */
 export interface CatalogPlace {
     readonly parent: NodeRef;
     readonly name: string;
-    /** Segment of the route of the catalog, when it is not the name. */
     readonly slug?: string;
-    /** Path of the directory of the catalog, as the site shows it. */
     readonly path: string;
 }
 /**
- * Adds query catalogs to the graph: one `catalog` node per directory, one
+ * @brief Adds query catalogs to the graph: one `catalog` node per directory, one
  * `query` node per entry, one `parameter` node per placeholder and one
  * `field` node per column of the rows an entry returns. A table an entry
  * names becomes a `reads` or a `writes` edge to that table.
@@ -42,6 +51,7 @@ export declare class CatalogPlanner {
     /**
      * Creates a planner.
      *
+     * @param graph - Receives the catalog, entry, parameter and field nodes.
      * @param markdown - Renders the notes of entries.
      * @param highlighter - Highlights the SQL of entries.
      * @param resolvers - Links what notes refer to.
@@ -51,6 +61,7 @@ export declare class CatalogPlanner {
     /**
      * Adds one catalog with its entries.
      *
+     * @param place - Where the catalog goes in the tree and what it is called.
      * @param files - The SQL files of the catalog, in display order.
      * @returns The node of the catalog.
      */
@@ -59,6 +70,8 @@ export declare class CatalogPlanner {
      * Adds one entry with its placeholders and its result columns.
      *
      * @param catalog - Node of the catalog.
+     * @param file - The SQL file the entry is in.
+     * @param query - The entry as parsed.
      * @param anchors - Anchors the catalog uses already. The anchor of the entry is added.
      * @returns The node of the entry.
      */
@@ -73,10 +86,11 @@ export declare class CatalogPlanner {
      */
     private columnOf;
     /**
-     * Replaces `*` and `t.*` in the result columns of an entry by the columns
+     * @brief Replaces `*` and `t.*` in the result columns of an entry by the columns
      * of the tables they stand for. That needs the tables at the time the
      * entry is added, so `DatabasePlanner` adds schema files first.
      *
+     * @param query - The entry whose result columns are expanded.
      * @param path - Display path (`SourceFile.displayPath`) of the file of the entry.
      * @returns The result columns, with every star replaced whose tables the scan has. Any other star stays.
      */

package/dist/scanner/sql/cursor.d.ts

@@ -1,12 +1,12 @@
 import type { SqlToken } from './tokens';
 /**
- * Error for a statement that cannot be read. Thrown by `TokenCursor` and by
+ * @brief Error for a statement that cannot be read. Thrown by `TokenCursor` and by
  * the readers of `parse.ts`. `parseSqlSchema` catches it and skips the statement.
  */
 export declare class SqlSyntaxError extends Error {
 }
 /**
- * Walks the tokens of one statement. Holds the tokens, the SQL text they come
+ * @brief Walks the tokens of one statement. Holds the tokens, the SQL text they come
  * from and the position of the cursor. The functions of `parse.ts` that read a
  * statement, a column or a constraint each take a cursor, read what they know
  * and leave the cursor behind it. `parseSqlSchema` creates one per statement,
@@ -19,6 +19,7 @@ export declare class TokenCursor {
     /**
      * Creates a cursor at the first token.
      *
+     * @param tokens - The tokens to walk, in order.
      * @param source - The SQL text the tokens come from, for reading text back as written.
      */
     constructor(tokens: readonly SqlToken[], source: string);
@@ -36,6 +37,7 @@ export declare class TokenCursor {
     /**
      * Takes the current token.
      *
+     * @returns The token the cursor was on.
      * @throws {SqlSyntaxError} At the end of the statement.
      */
     next(): SqlToken;
@@ -67,8 +69,7 @@ export declare class TokenCursor {
      */
     acceptSymbol(symbol: string): boolean;
     /**
-     * Takes a name: an unquoted word or a quoted identifier. A string counts,
-     * because SQLite reads a string as a name where a name has to be.
+     * Takes a name: an unquoted word, a quoted identifier or a string.
      *
      * @returns The name without quotes.
      * @throws {SqlSyntaxError} When the current token cannot be a name.
@@ -90,11 +91,15 @@ export declare class TokenCursor {
     /**
      * Reads SQL back as written, with runs of whitespace as one space.
      *
+     * @param from - First token of the text.
      * @param to - Last token of the text. Defaults to the token in front of the cursor.
      */
     text(from: SqlToken, to?: SqlToken | undefined): string;
     /**
      * Creates a cursor for some of the tokens of the same text.
+     *
+     * @param tokens - Tokens of part of the statement, from the same text.
+     * @returns A cursor at the first of them.
      */
     over(tokens: readonly SqlToken[]): TokenCursor;
 }

package/dist/scanner/sql/database.d.ts

@@ -5,13 +5,12 @@ import { type Reporter } from '../reporter';
 import type { CatalogPlanner } from './catalog';
 import type { SqlPlanner } from './planner';
 /**
- * Builds the database section from the SQL files of a directory tree.
+ * @brief Builds the database section from the SQL files of a directory tree.
  *
  * A file that creates a table is a schema and goes to the `SqlPlanner`.
  * Every other SQL file holds queries and statements. The files of one
  * directory form a catalog, which goes to the `CatalogPlanner`. The section
- * starts at the directory the SQL files share, so a reader is not led
- * through folders that hold nothing else.
+ * starts at the directory the SQL files share.
  *
  * `RepositoryScanner` creates one per scan and calls `planTree` once per
  * source directory. The `SqlPlanner` and the `CatalogPlanner` share one
@@ -36,6 +35,9 @@ export declare class DatabasePlanner {
     /**
      * Creates a planner.
      *
+     * @param graph - Receives the database section nodes.
+     * @param schemas - Plans the schema files.
+     * @param catalogs - Plans the query catalogs.
      * @param reporter - Receives files that cannot be read.
      */
     constructor(graph: GraphBuilder, schemas: SqlPlanner, catalogs: CatalogPlanner, reporter?: Reporter);
@@ -43,6 +45,7 @@ export declare class DatabasePlanner {
      * Adds every SQL file of `source` below `section`.
      *
      * @param section - Node of the database section.
+     * @param source - The SQL files to read, with their root and prefix.
      */
     planTree(section: NodeRef, source: Source): Promise<void>;
 }

package/dist/scanner/sql/parse.d.ts

@@ -1,78 +1,113 @@
-/** What a `REFERENCES` clause states. */
+/**
+ * What a `REFERENCES` clause states.
+ *
+ * @property table - Name of the referenced table.
+ * @property columns - Referenced columns. Empty when the clause names none, which means the primary key.
+ * @property onDelete - Action in capitals, or `''`.
+ * @property onUpdate - Action in capitals, or `''`.
+ */
 export interface ParsedReference {
-    /** Name of the referenced table. */
     readonly table: string;
-    /** Referenced columns. Empty when the clause names none, which means the primary key. */
     readonly columns: readonly string[];
-    /** Action in capitals, or `''`. */
     readonly onDelete: string;
     readonly onUpdate: string;
 }
-/** A foreign key of a table, from a column or from a table constraint. */
+/**
+ * A foreign key of a table, from a column or from a table constraint.
+ *
+ * @property name - Name of the constraint, or `''`.
+ * @property sourceColumns - Columns of the table that hold the key.
+ */
 export interface ParsedForeignKey extends ParsedReference {
-    /** Name of the constraint, or `''`. */
     readonly name: string;
-    /** Columns of the table that hold the key. */
     readonly sourceColumns: readonly string[];
 }
-/** One column of a table as its statement writes it. */
+/**
+ * One column of a table as its statement writes it.
+ *
+ * @property name - Name of the column.
+ * @property type - Declared type as written, with single spaces. `''` for a column without one.
+ * @property notNull - True when the column is declared `NOT NULL`.
+ * @property defaultValue - Default value as written, or `null`.
+ * @property constraints - Other constraints of the column as written, such as `UNIQUE`, `CHECK (n > 0)` or `COLLATE NOCASE`.
+ * @property description - Markdown from the comment behind or above the column.
+ */
 export interface ParsedColumn {
     readonly name: string;
-    /** Declared type as written, with single spaces. `''` for a column without one. */
     readonly type: string;
-    /** True when the column is declared `NOT NULL`. */
     readonly notNull: boolean;
-    /** Default value as written, or `null`. */
     readonly defaultValue: string | null;
-    /** Other constraints of the column as written, such as `UNIQUE`, `CHECK (n > 0)` or `COLLATE NOCASE`. */
     readonly constraints: readonly string[];
-    /** Markdown from the comment behind or above the column. */
     readonly description: string;
 }
-/** An index of a table, from a `CREATE INDEX` statement. */
+/**
+ * An index of a table, from a `CREATE INDEX` statement.
+ *
+ * @property name - Name of the index.
+ * @property columns - Indexed columns or expressions as written.
+ * @property unique - True for a `UNIQUE` index.
+ */
 export interface ParsedIndex {
     readonly name: string;
-    /** Indexed columns or expressions as written. */
     readonly columns: readonly string[];
     readonly unique: boolean;
 }
-/** One table of a schema. */
+/**
+ * One table of a schema.
+ *
+ * @property name - Name of the table.
+ * @property line - 1-based line of the statement.
+ * @property description - Markdown from the comment above the statement.
+ * @property columns - Columns of the table.
+ * @property primaryKey - Columns of the primary key, in key order.
+ * @property foreignKeys - Foreign keys of the table.
+ * @property constraints - Table constraints that are no key, as written.
+ * @property options - `WITHOUT ROWID`, `STRICT`, `VIRTUAL`, `TEMPORARY`.
+ * @property indexes - Indexes of the table.
+ */
 export interface ParsedTable {
     readonly name: string;
-    /** 1-based line of the statement. */
     readonly line: number;
-    /** Markdown from the comment above the statement. */
     readonly description: string;
     readonly columns: readonly ParsedColumn[];
-    /** Columns of the primary key, in key order. */
     readonly primaryKey: readonly string[];
     readonly foreignKeys: readonly ParsedForeignKey[];
-    /** Table constraints that are no key, as written. */
     readonly constraints: readonly string[];
-    /** `WITHOUT ROWID`, `STRICT`, `VIRTUAL`, `TEMPORARY`. */
     readonly options: readonly string[];
     readonly indexes: readonly ParsedIndex[];
 }
-/** A view or a trigger of a schema. */
+/**
+ * A view or a trigger of a schema.
+ *
+ * @property kind - `view` or `trigger`.
+ * @property name - Name of the view or trigger.
+ * @property table - The table a trigger fires on. `''` for a view.
+ * @property line - 1-based line of the statement.
+ * @property description - Markdown from the comment above the statement.
+ * @property sql - The statement as written, without the closing semicolon.
+ */
 export interface ParsedObject {
     readonly kind: 'view' | 'trigger';
     readonly name: string;
-    /** The table a trigger fires on. `''` for a view. */
     readonly table: string;
     readonly line: number;
     readonly description: string;
-    /** The statement as written, without the closing semicolon. */
     readonly sql: string;
 }
-/** What a schema file declares, from `parseSqlSchema`. */
+/**
+ * What a schema file declares, from `parseSqlSchema`.
+ *
+ * @property intro - Markdown from the comments that open the file.
+ * @property tables - Tables the file creates, in file order.
+ * @property objects - Views and triggers the file creates, in file order.
+ */
 export interface ParsedSchema {
-    /** Markdown from the comments that open the file. */
     readonly intro: string;
     readonly tables: readonly ParsedTable[];
     readonly objects: readonly ParsedObject[];
 }
 /**
- * Reads the tables, indexes, views and triggers of a SQLite schema file.
+ * @brief Reads the tables, indexes, views and triggers of a SQLite schema file.
  * Statements of any other kind, and statements that cannot be read, are
  * skipped. The SQL is read as text and never run.
  *

package/dist/scanner/sql/planner.d.ts

@@ -8,7 +8,7 @@ import { type Reporter } from '../reporter';
 import { type ParsedSchema } from './parse';
 import type { TableRegistry } from './registry';
 /**
- * Adds SQL schema files to the graph: one `database` node per file, one
+ * @brief Adds SQL schema files to the graph: one `database` node per file, one
  * `table` node per table and one `field` node per column. A foreign key
  * becomes a `references` edge from its table to the table it points at.
  *
@@ -27,6 +27,7 @@ export declare class SqlPlanner {
     /**
      * Creates a planner.
      *
+     * @param graph - Receives the database, table and field nodes.
      * @param markdown - Renders comments.
      * @param highlighter - Highlights the statements of views and triggers.
      * @param resolvers - Links what comments refer to.
@@ -41,6 +42,7 @@ export declare class SqlPlanner {
     /**
      * Reads one SQL file and adds its nodes when it creates a table.
      *
+     * @param file - The SQL file to read.
      * @param parent - Gives the folder or skill the file is in. Called only when the file creates a table, so a folder with nothing else in it is not added.
      * @returns The node of the file, or `null` when it creates no table or cannot be read.
      */
@@ -48,16 +50,18 @@ export declare class SqlPlanner {
     /**
      * Adds the nodes of one schema file.
      *
+     * @param file - The SQL file to add.
      * @param schema - What the file declares, from `parseSqlSchema`.
      * @param parent - The folder or skill the file is in.
      * @returns The node of the file.
      */
     add(file: SourceFile, schema: ParsedSchema, parent: NodeRef): NodeRef;
     /**
-     * Resolves a foreign key against the tables of the scan, and records the
+     * @brief Resolves a foreign key against the tables of the scan, and records the
      * edge to its target.
      *
      * @param from - Node of the table that holds the key.
+     * @param key - The foreign key as the statement wrote it.
      * @param path - Display path (`SourceFile.displayPath`) of the file the key is in.
      * @returns The key with its target, and with the primary key of the target as its columns when the statement names none.
      */

package/dist/scanner/sql/query.d.ts

@@ -1,53 +1,66 @@
 import type { QueryEffect, QueryTable } from '../../model';
-/** A column a statement names. */
+/**
+ * A column a statement names.
+ *
+ * @property table - Name of the table in front of the column, with an alias replaced by its table. `null` for a column without one.
+ * @property column - Name of the column. `*` for every column.
+ */
 export interface ParsedColumnRef {
-    /** Name of the table in front of the column, with an alias replaced by its table. `null` for a column without one. */
     readonly table: string | null;
-    /** Name of the column. `*` for every column. */
     readonly column: string;
 }
-/** One placeholder of a statement. */
+/**
+ * One placeholder of a statement.
+ *
+ * @property name - The placeholder as written: `:map_id`, `@id`, `$id`, `?2`. A plain `?` gets the number SQLite gives it: `?1`.
+ * @property column - The column the placeholder is compared with or stored in, when the statement shows one.
+ * @property count - True for the row count of a `LIMIT` or an `OFFSET`.
+ */
 export interface ParsedParameter {
-    /** The placeholder as written: `:map_id`, `@id`, `$id`, `?2`. A plain `?` gets the number SQLite gives it: `?1`. */
     readonly name: string;
-    /** The column the placeholder is compared with or stored in, when the statement shows one. */
     readonly column: ParsedColumnRef | null;
-    /** True for the row count of a `LIMIT` or an `OFFSET`. */
     readonly count: boolean;
 }
-/** One column of the rows a statement returns. */
+/**
+ * One column of the rows a statement returns.
+ *
+ * @property name - Name of the column in the result: its alias, else the column it selects, else the expression as written. `*` and `t.*` stand for every column of a table.
+ * @property expression - The expression behind an alias, as written. `''` for a column of a table.
+ * @property column - The column of a table it selects. `null` for an expression.
+ */
 export interface ParsedResultColumn {
-    /** Name of the column in the result: its alias, else the column it selects, else the expression as written. `*` and `t.*` stand for every column of a table. */
     readonly name: string;
-    /** The expression behind an alias, as written. `''` for a column of a table. */
     readonly expression: string;
-    /** The column of a table it selects. `null` for an expression. */
     readonly column: ParsedColumnRef | null;
 }
 /** A table a statement names, and what it does with it. */
 export type ParsedQueryTable = Pick<QueryTable, 'name' | 'access'>;
-/** One entry of a query catalog, as its file writes it. */
+/**
+ * One entry of a query catalog, as its file writes it.
+ *
+ * @property name - Name from a `-- name:` line above the SQL. `null` when the file has no such line, so the file names the entry.
+ * @property line - 1-based line the SQL starts on.
+ * @property effect - Whether the statement reads, writes or only controls.
+ * @property verb - The keywords that open the statement, in capitals: `SELECT`, `INSERT`, `BEGIN IMMEDIATE`.
+ * @property note - Markdown from the comments above the SQL.
+ * @property sql - The SQL as written, without the closing semicolon.
+ * @property parameters - Placeholders in the order SQLite numbers them, each once.
+ * @property tables - Tables the statement names, in the order they first appear, each once per access.
+ * @property columns - Result columns in result order. Empty for a statement that returns no rows.
+ */
 export interface ParsedQuery {
-    /** Name from a `-- name:` line above the SQL. `null` when the file has no such line, so the file names the entry. */
     readonly name: string | null;
-    /** 1-based line the SQL starts on. */
     readonly line: number;
     readonly effect: QueryEffect;
-    /** The keywords that open the statement, in capitals: `SELECT`, `INSERT`, `BEGIN IMMEDIATE`. */
     readonly verb: string;
-    /** Markdown from the comments above the SQL. */
     readonly note: string;
-    /** The SQL as written, without the closing semicolon. */
     readonly sql: string;
-    /** In the order SQLite numbers them, each once. */
     readonly parameters: readonly ParsedParameter[];
-    /** In the order they first appear, each once per access. */
     readonly tables: readonly ParsedQueryTable[];
-    /** In result order. Empty for a statement that returns no rows. */
     readonly columns: readonly ParsedResultColumn[];
 }
 /**
- * Reads a SQL file of a query catalog: a file of queries and statements that
+ * @brief Reads a SQL file of a query catalog: a file of queries and statements that
  * creates no table. The SQL is read as text and never run.
  *
  * A file is one entry, named by the file. A file that names its statements

package/dist/scanner/sql/registry.d.ts

@@ -1,32 +1,42 @@
 import type { NodeRef } from '../../model';
-/** A column of a table as the registry knows it. */
+/**
+ * A column of a table as the registry knows it.
+ *
+ * @property ref - Node of the column.
+ * @property name - Name of the column, as its table writes it.
+ * @property type - Declared type, or `''`.
+ */
 export interface ColumnEntry {
     readonly ref: NodeRef;
-    /** Name of the column, as its table writes it. */
     readonly name: string;
-    /** Declared type, or `''`. */
     readonly type: string;
 }
-/** A table as the registry knows it. */
+/**
+ * A table as the registry knows it.
+ *
+ * @property ref - Node of the table.
+ * @property name - Name of the table, as its statement writes it.
+ * @property path - Display path (`SourceFile.displayPath`) of the file that creates the table.
+ * @property primaryKey - Columns of its primary key, in key order.
+ * @property columns - Its columns, in table order.
+ */
 export interface TableEntry {
     readonly ref: NodeRef;
-    /** Name of the table, as its statement writes it. */
     readonly name: string;
-    /** Display path (`SourceFile.displayPath`) of the file that creates the table. */
     readonly path: string;
-    /** Columns of its primary key, in key order. */
     readonly primaryKey: readonly string[];
-    /** Its columns, in table order. */
     readonly columns: readonly ColumnEntry[];
 }
 /**
  * Finds a column of a table by name. Capitals do not matter, as in SQLite.
  *
+ * @param table - The table to search.
+ * @param name - Name of the column, in any case.
  * @returns The column, or `undefined` when the table has none of that name.
  */
 export declare function columnOf(table: TableEntry, name: string): ColumnEntry | undefined;
 /**
- * Finds tables by name across the SQL files of one scan.
+ * @brief Finds tables by name across the SQL files of one scan.
  *
  * `SqlPlanner` registers every table when it adds it, and looks tables up
  * when the content of the graph is built. By then every file is read, so a
@@ -37,7 +47,11 @@ export declare function columnOf(table: TableEntry, name: string): ColumnEntry |
  */
 export declare class TableRegistry {
     private readonly byName;
-    /** Records a table under its name. Capitals of the name do not matter, as in SQLite. */
+    /**
+     * Records a table under its name. Capitals of the name do not matter, as in SQLite.
+     *
+     * @param entry - The table to record.
+     */
     register(entry: TableEntry): void;
     /**
      * Finds the table a name in a SQL file means.

package/dist/scanner/sql/source.d.ts

@@ -3,6 +3,7 @@ import type { Reporter } from '../reporter';
 /**
  * Reads the text of a SQL file.
  *
+ * @param file - The SQL file to read, with its root and path.
  * @param reporter - Receives a warning when the file cannot be read.
  * @returns The text, or `null` for a file that is too large or cannot be read.
  */

package/dist/scanner/sql/statements.d.ts

@@ -7,7 +7,7 @@ import type { SqlComment, SqlToken } from './tokens';
  */
 export declare function markdownOf(comments: readonly SqlComment[]): string;
 /**
- * Finds the comments that describe what starts on a line: the comments on
+ * @brief Finds the comments that describe what starts on a line: the comments on
  * lines of their own directly above it, without a blank line between.
  *
  * @param comments - Every comment of the file, in file order.
@@ -15,12 +15,16 @@ export declare function markdownOf(comments: readonly SqlComment[]): string;
  * @returns The comments, in file order.
  */
 export declare function commentsAbove(comments: readonly SqlComment[], line: number): SqlComment[];
-/** One statement of a file, with its tokens. */
+/**
+ * One statement of a file: the tokens it is made of, without its closing semicolon.
+ *
+ * @property tokens - Tokens of the statement, in text order.
+ */
 export interface Statement {
     readonly tokens: readonly SqlToken[];
 }
 /**
- * Splits the tokens of a file into statements at the semicolons. The
+ * @brief Splits the tokens of a file into statements at the semicolons. The
  * semicolons inside the body of a trigger do not end its statement.
  *
  * @param tokens - Every token of the file.
@@ -31,6 +35,8 @@ export declare function statementsOf(tokens: readonly SqlToken[]): Statement[];
  * Reads a statement back as written.
  *
  * @param source - Text of the whole file.
+ * @param first - Token the statement starts with.
+ * @param last - Token the statement ends with.
  * @returns The statement with its line breaks, without the closing semicolon.
  */
 export declare function sqlOf(source: string, first: SqlToken, last: SqlToken): string;

package/dist/scanner/sql/tokens.d.ts

@@ -1,31 +1,43 @@
 /** What a token of a SQL text is. A `name` is a quoted identifier. */
 export type SqlTokenKind = 'word' | 'name' | 'string' | 'number' | 'symbol';
-/** One token of a SQL text. Comments are no tokens. */
+/**
+ * One token of a SQL text. Comments are no tokens.
+ *
+ * @property kind - What the token is.
+ * @property value - The token without quotes and escapes. For a word, a number or a symbol: the token as written.
+ * @property line - 1-based line the token starts on.
+ * @property endLine - 1-based line the token ends on.
+ * @property start - Offset of the first character in the text.
+ * @property end - Offset behind the last character.
+ */
 export interface SqlToken {
     readonly kind: SqlTokenKind;
-    /** The token without quotes and escapes. For a word, a number or a symbol: the token as written. */
     readonly value: string;
-    /** 1-based line the token starts on. */
     readonly line: number;
-    /** 1-based line the token ends on. */
     readonly endLine: number;
-    /** Offset of the first character in the text. */
     readonly start: number;
-    /** Offset behind the last character. */
     readonly end: number;
 }
-/** One comment of a SQL text. */
+/**
+ * One comment of a SQL text.
+ *
+ * @property lines - The comment without its markers, one entry per line.
+ * @property line - 1-based line the comment starts on.
+ * @property endLine - 1-based line the comment ends on.
+ * @property alone - True when no token is in front of the comment on its line.
+ */
 export interface SqlComment {
-    /** The comment without its markers, one entry per line. */
     readonly lines: readonly string[];
-    /** 1-based line the comment starts on. */
     readonly line: number;
-    /** 1-based line the comment ends on. */
     readonly endLine: number;
-    /** True when no token is in front of the comment on its line. */
     readonly alone: boolean;
 }
-/** The tokens and the comments of a SQL text, from `tokenizeSql`. */
+/**
+ * The tokens and the comments of a SQL text, from `tokenizeSql`.
+ *
+ * @property tokens - Tokens in text order.
+ * @property comments - Comments apart from the tokens, in text order.
+ */
 export interface SqlTokens {
     readonly tokens: readonly SqlToken[];
     readonly comments: readonly SqlComment[];
@@ -33,6 +45,7 @@ export interface SqlTokens {
 /**
  * Splits a SQL text into tokens and comments.
  *
+ * @param source - The SQL text, as written in the file.
  * @returns The tokens in text order, and the comments apart from them. Text that is no SQL becomes symbol tokens, so the function never fails.
  */
 export declare function tokenizeSql(source: string): SqlTokens;