IF Commons GitHub

extensions/docs/doc

Documentation as a value (commons lang-sql 0004-sql-docs FR-003 to FR-005): a summary, a description and tags, read from the text of comments as TSDoc reads it. The tags param, returns, example, deprecated, since and see are typed; any other is a tag with its name and text, or the value a reader a project gave for it makes.

The summary is the first paragraph with its lines joined by a space; the description is the paragraphs after it, before the first tag, with their line breaks kept; a tag begins on a line whose first character is @ and a name, and its text goes on until the next tag. The code of an example is parsed with the dialect it is given.

parseDoc("The people.\n\n@since 2026\n@param id the key").tags.map((t) => t.kind); // ["since", "param"]

Spec: 0004-sql-docs FR-003, FR-004, FR-005

Source: commons/lang-sql/src/extensions/docs/doc.ts

1 of 9 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

CustomTaginterfaceno test imports it
interface CustomTag

Any other tag, with the value of the reader a project gave for it.

MemberTypeWhat it is
kind"custom"
tagstring
textstring
valueunknown
Docinterfaceno test imports it
interface Doc

Documentation.

MemberTypeWhat it is
rawstringAll of the text, with the markers taken off.
summarystring
descriptionstring
tagsreadonly DocTag[]
DocOptionsinterfaceno test imports it
interface DocOptions

What parseDoc may be given.

MemberTypeWhat it is
dialect?DialectThe dialect the examples are parsed in; the base dialect by default.
readers?Readonly<Record<string, (text: string) => unknown>>Readers for tags of a project's own, by tag name; each is given the text of the tag.
DocTagtypeno test imports it
type DocTag = ParamTag | ReturnsTag | ExampleTag | NoteTag | CustomTag;

A tag of a documentation.

ExampleTaginterfaceno test imports it
interface ExampleTag

An @example: its code and what the parser made of it.

MemberTypeWhat it is
kind"example"
tagstring
codestring
parsedParsed
NoteTaginterfaceno test imports it
interface NoteTag

A @deprecated, @since or @see.

MemberTypeWhat it is
kind"deprecated" | "see" | "since"
tagstring
textstring
ParamTaginterfaceno test imports it
interface ParamTag

A @param name {type} text.

MemberTypeWhat it is
kind"param"
tagstring
namestring
typestring | undefined
textstring
parseDocfunction
function parseDoc(text: string, options?: DocOptions): Doc

Reads documentation from text.

ParameterWhat it is
textthe text of comments with their markers taken off (see docText)
optionsthe dialect for the examples, and readers for a project's tags

Returns: the summary, the description and the tags

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

ReturnsTaginterfaceno test imports it
interface ReturnsTag

A @returns text.

MemberTypeWhat it is
kind"returns"
tagstring
textstring

Titles, headings, exports, tables, columns and requirements. Esc closes.