@g3nomaly/analyze 0.1.0 → 0.1.1

package/dist/scanner/code/language.d.ts

@@ -1,7 +1,8 @@
 import type { SymbolKind } from '../../model';
 import type { Node } from 'web-tree-sitter';
 /**
- * Doc comment dialect.
+ * @brief Doc comment dialect, which decides how the scanner reads doc comments.
+ *
  * - `tagged`: `@param`-style tags (JSDoc, Javadoc, Doxygen, PHPDoc, KDoc, Scaladoc).
  * - `yard`: `tagged`, with the title of an `@example` on the tag line.
  * - `markdown`: free markdown with headed sections (rustdoc, godoc).
@@ -9,141 +10,174 @@ import type { Node } from 'web-tree-sitter';
  * - `xml`: C# XML documentation.
  */
 export type DocStyle = 'tagged' | 'yard' | 'markdown' | 'python' | 'xml';
-/** What a language spec can inspect when it classifies one definition. */
+/**
+ * What a language spec can inspect when it classifies one definition.
+ *
+ * @property node - Tree-sitter node of the definition.
+ * @property signature - Declaration head, without the body.
+ * @property annotations - Decorator, attribute and annotation texts in front of the definition.
+ * @property returnType - Declared return type text, e.g. `number`, or `null` when the grammar exposes none.
+ * @property hasReceiver - True when the parameter list starts with a receiver such as `self`.
+ */
 export interface DefinitionFacts {
     readonly node: Node;
-    /** Declaration head, without the body. */
     readonly signature: string;
     readonly annotations: readonly string[];
-    /** Declared return type text, when the grammar exposes one. */
     readonly returnType: string | null;
-    /** True when the parameter list starts with a receiver such as `self`. */
     readonly hasReceiver: boolean;
 }
-/** What an import hook knows about the symbol an example uses. */
+/**
+ * What an import hook knows about the symbol an example uses.
+ *
+ * @property filePath - Root-relative path of the file that declares the symbol.
+ * @property name - Outermost symbol around the one the example uses: the class of a method, or the function itself.
+ * @property kind - Kind of that outermost symbol.
+ * @property modifiers - Keywords in front of the name, such as `export` or `default`.
+ * @property packageName - Package or namespace the file declares with a statement, e.g. `a.b` for Java's `package a.b;`, or `null`.
+ */
 export interface ImportContext {
-    /** Root-relative path of the file that declares the symbol. */
     readonly filePath: string;
-    /** Outermost symbol around the one the example uses: the class of a method, or the function itself. */
     readonly name: string;
     readonly kind: SymbolKind;
     readonly modifiers: readonly string[];
-    /** Package or namespace the file declares with a statement, such as Java's `package a.b;`. */
     readonly packageName: string | null;
 }
-/** How a language spells a call. Drives generated examples. */
+/**
+ * How a language spells a call. Drives generated examples.
+ *
+ * @property terminator - Statement terminator, `';'` or `''`.
+ * @property variableCase - Case of generated variable names.
+ * @property variablePrefix - Prefix of variable names, `'$'` in PHP.
+ * @property memberAccess - Operator between an instance and its member, e.g. `.` or `->`.
+ * @property staticAccess - Operator between a type and its static member, e.g. `::`.
+ * @property namespaceAccess - Separator between a namespace and its member, or `null` when members are called unqualified.
+ */
 export interface CallStyle {
-    /** Statement terminator, `';'` or `''`. */
     readonly terminator: string;
     readonly variableCase: 'camel' | 'snake';
-    /** Prefix of variable names, `'$'` in PHP. */
     readonly variablePrefix?: string;
     readonly memberAccess: string;
     readonly staticAccess: string;
-    /** Separator between a namespace and its member. `null` means members are called unqualified. */
     readonly namespaceAccess: string | null;
     /** Binds the value of `expression` to `variable`. */
     declare(variable: string, expression: string, returnType: string | null): string;
     /**
-     * Statement that creates an instance of `type` named `variable`.
-     * `hasConstructor` is false when the scanner found no constructor in the file.
-     * Returns `null` when the language cannot build the type without one.
+     * @brief Statement that creates an instance of `type` named `variable`.
+     *
+     * @param hasConstructor - False when the scanner found no constructor in the file.
+     * @returns The statement, or `null` when the language cannot build the type without a constructor.
      */
     construct(type: string, args: string, variable: string, hasConstructor: boolean): string | null;
     /** Wraps an expression that must be awaited. */
     await?(expression: string): string;
-    /** Rewrites one argument, for languages with named arguments. */
+    /**
+     * Rewrites one argument, for languages with named arguments.
+     *
+     * @param parameter - Declaration node of the parameter the argument fills.
+     */
     argument?(name: string, parameter: Node): string;
-    /** Line that brings the symbol into scope, or `null` when it cannot be derived. */
+    /**
+     * Line that brings the symbol into scope.
+     *
+     * @param context - What the import needs to know about the symbol.
+     * @returns The import line, or `null` when it cannot be derived.
+     */
     importLine?(context: ImportContext): string | null;
 }
 /**
- * Everything the scanner needs to support one language. Adding a language
- * means adding one spec and listing it in `languages/index.ts`.
+ * @brief Everything the scanner needs to support one language.
+ *
+ * Adding a language means adding one spec and listing it in `languages/index.ts`.
+ *
+ * @property id - Unique language id, e.g. `typescript`.
+ * @property label - Display name of the language, e.g. `TypeScript`.
+ * @property family - Languages whose types can refer to each other, such as TypeScript and JavaScript. A type name never links across families. Defaults to `id`.
+ * @property extensions - File extensions the language claims, e.g. `.ts`.
+ * @property accepts - For an extension several languages share, such as `.h`: answers whether this source is in this language. Specs are tried in registry order.
+ * @property grammarPath - Path of the tree-sitter grammar `.wasm`.
+ * @property highlight - shiki language id.
+ * @property query - Tree-sitter query. Captures `@definition.<kind>` on the definition node, `@name`, and optionally `@params`, `@body`, `@return`, `@owner`, `@type`, `@value`, `@receiver`, `@package`. `@owner` names the type a method declared outside it belongs to. `@definition.field` marks a field, property or enum member. With `@receiver` (Python's `self.x = ...`) the field belongs to the type around the enclosing method.
+ * @property typeSyntax - Where a declaration puts its type: `prefix` as in `int count`, `suffix` as in `count: int`, `none` for languages without declared types.
+ * @property annotationLabel - What the language calls its annotations, for example `Decorators`.
+ * @property docStyle - Dialect of the doc comments.
+ * @property docSource - Where documentation lives: `leading-comment` above the definition, or `docstring`, the first string of the body.
+ * @property commentTypes - Node types of comments.
+ * @property isDocComment - Restricts which leading comments count as documentation.
+ * @property annotationTypes - Node types of decorators, attributes and annotations.
+ * @property wrapperTypes - Parent node types that wrap a definition, such as `export_statement`.
+ * @property localScopeTypes - Node types whose descendants are local, such as closures.
+ * @property hoistedCommentParents - Parents whose leading comment documents their first child.
+ * @property receiverTypes - Parameter node types that are receivers.
+ * @property receiverNames - Parameter names that are receivers.
+ * @property skippedParamTypes - Parameter node types that never appear in a call.
+ * @property paramTypes - When set, only these node types inside a parameter list are parameters.
+ * @property isInstantiable - Answers from a declaration head whether the type can be constructed. Abstract types are excluded already.
+ * @property inferredOwnerKind - Kind given to an owner type that is not declared in the same file.
+ * @property splitQualifiedName - Splits a qualified name such as `Foo::bar` into owner and member.
+ * @property declaredReturnType - Reads the return type when the `@return` capture cannot express it, such as a C pointer.
+ * @property call - How the language spells a call.
  */
 export interface LanguageSpec {
     readonly id: string;
     readonly label: string;
-    /**
-     * Languages whose types can refer to each other, such as TypeScript and
-     * JavaScript. A type name never links across families. Defaults to `id`.
-     */
     readonly family?: string;
     readonly extensions: readonly string[];
-    /**
-     * For an extension that several languages share, such as `.h`: answers
-     * whether this source is in this language. Specs are tried in registry order.
-     */
     readonly accepts?: (source: string) => boolean;
-    /** Path of the tree-sitter grammar `.wasm`. */
     readonly grammarPath: string;
-    /** shiki language id. */
     readonly highlight: string;
-    /**
-     * Tree-sitter query. Captures: `@definition.<kind>` on the definition node,
-     * `@name`, and optionally `@params`, `@body`, `@return`, `@owner`.
-     * `@owner` names the type a method belongs to when the method is declared
-     * outside it (Go receivers, Rust `impl` blocks).
-     *
-     * `@definition.field` marks a field, property or enum member. It takes
-     * `@name` and optionally `@type` and `@value`. With `@receiver` (Python's
-     * `self.x = ...`) the field belongs to the type around the enclosing method.
-     *
-     * `@package` captures the package or namespace the file declares.
-     */
     readonly query: string;
-    /**
-     * Where a declaration puts its type: `prefix` as in `int count`, `suffix`
-     * as in `count: int`, `none` for languages without declared types.
-     */
     readonly typeSyntax: 'prefix' | 'suffix' | 'none';
-    /** What the language calls its annotations, for example `Decorators`. */
     readonly annotationLabel: string;
     readonly docStyle: DocStyle;
-    /** `docstring` reads the first string of the body instead of leading comments. */
     readonly docSource: 'leading-comment' | 'docstring';
     readonly commentTypes: readonly string[];
-    /** Restricts which leading comments count as documentation. */
     readonly isDocComment?: (text: string) => boolean;
-    /** Node types of decorators, attributes and annotations. */
     readonly annotationTypes: readonly string[];
-    /** Parent node types that wrap a definition, such as `export_statement`. */
     readonly wrapperTypes: readonly string[];
-    /** Node types whose descendants are local, such as closures. */
     readonly localScopeTypes: readonly string[];
-    /** Parents whose leading comment documents their first child (a tree-sitter-ruby quirk). */
     readonly hoistedCommentParents?: readonly string[];
-    /** Parameter node types that are receivers. */
     readonly receiverTypes?: readonly string[];
-    /** Parameter names that are receivers. */
     readonly receiverNames?: readonly string[];
-    /** Parameter node types that never appear in a call. */
     readonly skippedParamTypes?: readonly string[];
-    /** When set, only these node types inside a parameter list are parameters. */
     readonly paramTypes?: readonly string[];
-    /** Answers from a declaration head whether the type can be constructed. Abstract types are excluded already. */
     readonly isInstantiable?: (signature: string) => boolean;
-    /** Kind given to an owner type that is not declared in the same file. */
     readonly inferredOwnerKind?: SymbolKind;
-    /** Splits a qualified name such as `Foo::bar` into owner and member. */
     readonly splitQualifiedName?: (name: string) => {
         owner: string;
         name: string;
     } | null;
-    /** Names a constructor can have inside a class called `className`. */
+    /**
+     * Names a constructor can have inside a class called `className`.
+     *
+     * @param className - Name of the class the constructor belongs to.
+     */
     constructorNames(className: string): readonly string[];
-    /** True when the definition is called on its type rather than on an instance. */
+    /**
+     * True when the definition is called on its type rather than on an instance.
+     *
+     * @param facts - What the spec can inspect about the definition.
+     */
     isStatic(facts: DefinitionFacts): boolean;
-    /** True when a call to the definition yields a value, so a generated example binds it to a variable. */
+    /**
+     * True when a call to the definition yields a value, so a generated example binds it to a variable.
+     *
+     * @param facts - What the spec can inspect about the definition.
+     */
     returnsValue(facts: DefinitionFacts): boolean;
-    /** Reads the return type when the `@return` capture cannot express it, such as a C pointer. */
     readonly declaredReturnType?: (facts: DefinitionFacts) => string | null;
     readonly call: CallStyle;
 }
-/** Language family of a spec: its `family`, or its `id` when it sets none. */
+/**
+ * Language family of a spec.
+ *
+ * @param spec - Spec to read.
+ * @returns Its `family`, or its `id` when it sets none.
+ */
 export declare function familyOf(spec: LanguageSpec): string;
 /**
  * Decides from a declared return type whether a call yields a value.
- * `implicit` answers for declarations without a return type.
+ *
+ * @param returnType - Declared return type text, or `null` when the declaration has none.
+ * @param implicit - Answer for declarations without a return type.
  */
 export declare function returnsValueFrom(returnType: string | null, implicit: boolean): boolean;

package/dist/scanner/code/languages/index.d.ts

@@ -2,18 +2,32 @@ import type { LanguageSpec } from '../language';
 /** Every supported language. Add a spec here to support another one. */
 export declare const LANGUAGES: readonly LanguageSpec[];
 /**
- * Maps files to language specs, by extension and, where languages share one, by content.
+ * @brief Maps files to language specs, by extension and, where languages share one, by content.
  *
- * Holds the specs that claim each lowercase extension, in registry order. Created by
- * `RepositoryScanner` in `scanner/scanner.ts` and consumed by `CodePlanner` in
- * `code/planner.ts`.
+ * Holds the specs that claim each lowercase extension, in registry order. Created with
+ * `new LanguageRegistry()` by `RepositoryScanner` in `scanner/scanner.ts`, and consumed by
+ * `CodePlanner` in `code/planner.ts`.
  */
 export declare class LanguageRegistry {
     private readonly byExtension;
-    /** Indexes the specs by extension. Order matters: `forFile` tries them in this order. */
+    /**
+     * Indexes the specs by extension. Order matters: `forFile` tries them in this order.
+     *
+     * @param languages - Specs to index, in priority order. Defaults to {@link LANGUAGES}.
+     */
     constructor(languages?: readonly LanguageSpec[]);
-    /** True when some language claims the extension of `path`. */
+    /**
+     * True when some language claims the extension of `path`.
+     *
+     * @param path - File path; the extension is matched case-insensitively.
+     */
     supports(path: string): boolean;
-    /** The first language that accepts the source. Falls back to the last one that claims the extension. */
+    /**
+     * The first language that accepts the source. Falls back to the last one that claims the extension.
+     *
+     * @param path - File path; its extension selects the candidates.
+     * @param source - Full text of the file, given to each candidate's `accepts`.
+     * @returns The chosen spec, or `null` when no language claims the extension.
+     */
     forFile(path: string, source: string): LanguageSpec | null;
 }

package/dist/scanner/code/languages/shared.d.ts

@@ -1,17 +1,36 @@
 import type { Node } from 'web-tree-sitter';
 import type { DefinitionFacts, ImportContext } from '../language';
-/** True when the declaration head contains the `static` keyword. */
+/**
+ * True when the declaration head contains the `static` keyword.
+ *
+ * @param facts - What the spec can inspect about the definition.
+ */
 export declare function hasStaticKeyword(facts: DefinitionFacts): boolean;
 /**
- * Walks up from a definition and reports whether it reaches one of `staticScopes`
+ * @brief Walks up from a definition and reports whether it reaches one of `staticScopes`
  * before one of `instanceScopes`. Used for Kotlin and Scala `object` members.
+ *
+ * @param node - Tree-sitter node of the definition.
+ * @param staticScopes - Node types whose members are static.
+ * @param instanceScopes - Node types whose members are instance members, which stop the walk.
  */
 export declare function isInsideScope(node: Node, staticScopes: readonly string[], instanceScopes: readonly string[]): boolean;
 /** False for a Kotlin or Scala `object` declaration head, which declares a singleton. */
 export declare function isNotSingleton(signature: string): boolean;
-/** `*` or `&` when a C or C++ function returns a pointer or reference, which the `type` field does not show. */
+/**
+ * `*` or `&` when a C or C++ function returns a pointer or reference, which the `type` field does not show.
+ *
+ * @param node - Function definition node.
+ * @returns One mark per pointer or reference layer, or `''` for a plain return.
+ */
 export declare function returnIndirection(node: Node): string;
 /** Path of a file without its extension, for module specifiers. */
 export declare function withoutExtension(path: string): string;
-/** `import pkg.Name` in the given statement shape, for languages with a declared package. */
+/**
+ * `import pkg.Name` in the given statement shape, for languages with a declared package.
+ *
+ * @param context - What the import needs to know about the symbol.
+ * @param format - Builds the statement from the qualified name, such as `import pkg.Name;`.
+ * @returns The statement, or `null` when the file declares no package.
+ */
 export declare function packageImport(context: ImportContext, format: (qualifiedName: string) => string): string | null;

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

@@ -1,4 +1,5 @@
 import type { NodeRef } from '../../model';
+import type { ConfigPlanner } from '../config';
 import type { FileRenderer } from '../content';
 import { type Source } from '../files';
 import type { GraphBuilder } from '../graph/builder';
@@ -8,17 +9,22 @@ import type { SymbolExtractor } from './extract';
 import type { GrammarLoader } from './grammar';
 import type { LanguageRegistry } from './languages';
 import type { SymbolPlanner } from './symbols';
-/** One source file to add. */
+/**
+ * @brief One source file to add.
+ *
+ * @property root - Absolute directory `path` is relative to.
+ * @property path - Path of the file below `root`, in POSIX form.
+ * @property displayPath - Path as the bundle shows it: `path` behind the prefix of its source.
+ */
 export interface SourceFile {
-    /** Absolute directory `path` is relative to. */
     readonly root: string;
     readonly path: string;
-    /** Path as the bundle shows it: `path` behind the prefix of its source. */
     readonly displayPath: string;
 }
 /**
- * Adds source files and their symbols to the graph. The SQL files of a
- * repository are no code: `DatabasePlanner` adds them. A SQL file of a skill
+ * @brief Adds source files and their symbols to the graph.
+ *
+ * The SQL files of a repository are no code: `DatabasePlanner` adds them. A SQL file of a skill
  * that creates tables goes to the `SqlPlanner`.
  *
  * Holds the planners and loaders it delegates to: it parses a file with the
@@ -43,29 +49,59 @@ export declare class CodePlanner {
     /**
      * Takes the graph it adds nodes to and the helpers it delegates each file to.
      *
+     * @param graph - Graph the source nodes are added to.
+     * @param registry - Says which languages are supported and which spec reads a file.
+     * @param grammars - Loads the parser and query of a language spec.
+     * @param extractor - Extracts the raw symbols from a parsed syntax tree.
+     * @param symbols - Adds the symbols of a file below its source node.
+     * @param files - Reads the text of a file, to embed it in its node.
+     * @param sql - Adds SQL files that create tables as databases.
      * @param reporter - Receives a warning for each file that cannot be read or parsed. Silent by default.
      */
     constructor(graph: GraphBuilder, registry: LanguageRegistry, grammars: GrammarLoader, extractor: SymbolExtractor, symbols: SymbolPlanner, files: FileRenderer, sql: SqlPlanner, reporter?: Reporter);
-    /** True for a file that is source code, whether or not the scanner can read its symbols. */
+    /**
+     * @brief Tells whether a file is source code, whether or not the scanner can read its symbols.
+     *
+     * @param path - Path of the file, with its extension.
+     */
     isSource(path: string): boolean;
     /**
-     * Adds every file of `source` that declares a class or a function, in
-     * folders below `section`. Files in unsupported languages are skipped.
+     * @brief Adds every file of `source` that declares a class or a function, in folders below `section`.
+     *
+     * Files in unsupported languages are skipped. JSON, TOML and YAML files go to `configs`, in the same
+     * pass, so the tree stays in path order.
+     *
+     * @param section - Node the folders are added below.
+     * @param source - Directory whose files are read.
+     * @param configs - Plans the JSON, TOML and YAML files. Without it they are skipped.
      */
-    planTree(section: NodeRef, source: Source): Promise<void>;
+    planTree(section: NodeRef, source: Source, configs?: ConfigPlanner): Promise<void>;
     /**
-     * Adds one file below `parent` with its text embedded, whatever it
-     * declares. Used for the code that belongs to a skill. A SQL file that
-     * creates tables is added as a database instead.
+     * @brief Adds one file below `parent` with its text embedded, whatever it declares.
+     *
+     * A SQL file that creates tables is added as a database instead.
+     *
+     * @param parent - Node the file is added below.
+     * @param file - File to add.
+     * @returns Node of the file, or of the database it creates.
      */
     planFile(parent: NodeRef, file: SourceFile): Promise<NodeRef>;
     /**
-     * Adds a `source` node for the file below `parent`, registers its display path, and plans its symbols.
+     * @brief Adds a `source` node for the file below `parent`, registers its display path, and plans its symbols.
      *
+     * @param parent - Node the file is added below.
+     * @param file - File to add.
      * @param extracted - Symbols of the file, or `null` to add the file without symbols.
      * @param embedText - Whether the node carries the file's full text.
+     * @returns Node of the file.
      */
     private add;
-    /** The symbols of a file, or `null` when its language is unsupported or it cannot be read. */
+    /**
+     * @brief Reads the symbols of a file.
+     *
+     * @param file - File to read.
+     * @returns Symbols with their language spec, or `null` when the language is unsupported, the file is
+     * missing or larger than `MAX_SOURCE_BYTES`, or it cannot be parsed.
+     */
     private extract;
 }

package/dist/scanner/code/symbols.d.ts

@@ -6,22 +6,26 @@ import type { MarkdownRenderer } from '../markdown/renderer';
 import type { RawSymbol } from './extract';
 import { type LanguageSpec } from './language';
 import type { CallableIndex, TypeIndex, TypeLinker } from './types';
-/** What the planner needs to know about the file a symbol tree comes from. */
+/**
+ * @brief What the planner needs to know about the file a symbol tree comes from.
+ *
+ * @property spec - Language spec that reads the file.
+ * @property path - Display path of the file: its path below the source root, behind the source's prefix.
+ * @property packageName - Package or namespace the file declares, or `null`.
+ */
 export interface FileContext {
     readonly spec: LanguageSpec;
-    /** Display path of the file: its path below the source root, behind the source's prefix. */
     readonly path: string;
-    /** Package or namespace the file declares. */
     readonly packageName: string | null;
 }
 /**
- * Adds the symbols of a file to the graph: one node per class or function,
- * with a child node per parameter and field. Type names in signatures become
- * links to the types they name.
+ * @brief Adds the symbols of a file to the graph: one node per class or function,
+ * with a child node per parameter and field.
  *
- * Holds the graph, the renderers, and the indexes and linkers it registers into and
- * links through. Created per scan by `RepositoryScanner` in `scanner/scanner.ts`;
- * `CodePlanner` in `planner.ts` calls `plan` for each file it extracts symbols from.
+ * Type names in signatures become links to the types they name. Holds the graph, the renderers,
+ * and the indexes and linkers it registers into and links through. Created per scan by
+ * `RepositoryScanner` in `scanner/scanner.ts`; `CodePlanner` in `planner.ts` calls `plan` for
+ * each file it extracts symbols from.
  *
  * @example
  * const symbols = new SymbolPlanner(graph, highlighter, markdown, types, callables, linker, resolvers);
@@ -35,34 +39,96 @@ export declare class SymbolPlanner {
     private readonly callables;
     private readonly linker;
     private readonly resolvers;
-    /** Takes the graph and renderers it writes with, and the indexes and linkers that resolve names. */
+    /**
+     * Takes the graph and renderers it writes with, and the indexes and linkers that resolve names.
+     *
+     * @param graph - Graph the symbol nodes are added to.
+     * @param highlighter - Highlights signatures and examples as HTML.
+     * @param markdown - Renders doc descriptions as HTML.
+     * @param types - Index of type declarations, where each new type is registered.
+     * @param callables - Index of functions and methods, where each new callable is registered.
+     * @param linker - Links the type names of signatures to their declarations.
+     * @param resolvers - Resolves the names in prose descriptions to links.
+     */
     constructor(graph: GraphBuilder, highlighter: CodeHighlighter, markdown: MarkdownRenderer, types: TypeIndex, callables: CallableIndex, linker: TypeLinker, resolvers: ProseResolvers);
-    /** Adds `symbols` and everything inside them below the file node `fileRef`. */
+    /**
+     * @brief Adds `symbols` and everything inside them below the file node `fileRef`.
+     *
+     * @param fileRef - Node of the file the symbols are in.
+     * @param file - Language spec and path of the file.
+     * @param symbols - Top-level symbols of the file, in file order.
+     */
     plan(fileRef: NodeRef, file: FileContext, symbols: readonly RawSymbol[]): void;
     /**
-     * Adds one symbol node with its parameter and field nodes, registers it in the type or
+     * @brief Adds one symbol node with its parameter and field nodes, registers it in the type or
      * callable index, and recurses into its children.
+     *
+     * @param symbol - Symbol to add, as the extractor found it.
+     * @param scope - Where the symbol sits in the file.
      */
     private planSymbol;
     /**
-     * Builds the content of a symbol node: highlighted signature, rendered description,
-     * return value, tags and example. Records `extends` edges for its heritage.
+     * @brief Builds the content of a symbol node: highlighted signature, rendered description,
+     * return value, tags and example.
+     *
+     * Records `extends` edges for its heritage.
      *
+     * @param symbol - Symbol the content is built for.
+     * @param doc - Parsed doc comment of the symbol.
+     * @param scope - Where the symbol sits in the file.
+     * @param typeScope - Scope that the names of the symbol resolve in.
      * @param self - Node of the symbol itself, where the edges start.
+     * @returns Content of the symbol node.
      */
     private symbolContent;
-    /** Builds the content of a parameter or field node: linked type, default, optional flag and rendered description. */
+    /**
+     * @brief Builds the content of a parameter or field node: linked type, default, optional flag and rendered description.
+     *
+     * @param declaration - Parameter or field to build the content of.
+     * @param self - Node of the parameter or field itself, where the type edge starts.
+     * @param file - File the declaration is in.
+     * @param typeScope - Scope that the type name resolves in.
+     * @returns Content of the node.
+     */
     private declarationContent;
     /**
-     * Return value of a symbol from its declared return type and `@returns` tag.
+     * @brief Builds the return value of a symbol from its declared return type and `@returns` tag.
      *
-     * @returns `null` when there is no tag and the symbol returns no typed value.
+     * @param symbol - Symbol whose return value is built.
+     * @param doc - Parsed doc comment of the symbol.
+     * @param self - Node of the symbol, where the type edge starts.
+     * @param file - File the symbol is in.
+     * @param typeScope - Scope that the type name resolves in.
+     * @returns The return value, or `null` when there is no tag and the symbol returns no typed value.
      */
     private returns;
-    /** Prefers the documented example. Falls back to one generated from the signature. */
+    /**
+     * @brief Builds the example of a symbol: the documented one, or one generated from its signature.
+     *
+     * @param symbol - Symbol the example is for.
+     * @param scope - Where the symbol sits in the file.
+     * @param documented - Example from the doc comment, or `null` when there is none.
+     * @returns The highlighted example with its origin, or `null` when none can be built.
+     */
     private example;
-    /** Renders a plain doc tag. The subject of a `throws` tag links to the types it names. */
+    /**
+     * @brief Renders a plain doc tag. The subject of a `throws` tag links to the types it names.
+     *
+     * @param tag - Tag to render.
+     * @param self - Node of the symbol the tag belongs to.
+     * @param file - File the symbol is in.
+     * @param typeScope - Scope that the names in the tag resolve in.
+     * @returns The tag as the symbol's page shows it.
+     */
     private tag;
-    /** Renders a description. Inline code that names a type or function, and glossary terms, become links. */
+    /**
+     * @brief Renders a description. Inline code that names a type or function, and glossary terms, become links.
+     *
+     * @param markdown - Markdown to render.
+     * @param from - Node the description belongs to. Links start here.
+     * @param file - File the description is in.
+     * @param typeScope - Scope that the names in the description resolve in.
+     * @returns The rendered HTML, `''` for an empty description.
+     */
     private html;
 }