IF Commons GitHub

Documentation extracted from SQL comments

0004Active

0004-sql-docs · owner if · domain data

What is documentation

FR-001checkpassing

The text of a comment MUST be read as documentation with its markers taken off: a line comment loses its marker, any run of the marker's last character that follows it (---, ///, ##) and one space; a block comment loses its delimiters, and on each line its leading white space, any * and one space, with empty lines at its start and end dropped; consecutive comments are joined by a new line; and the kind of comment MUST NOT matter, so that every kind a dialect has (--, #, //, #!, block comments, hints) can carry documentation.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/docs.test.ts: the text of a comment has its markers taken off, whatever kind of comment the dialect has, and consecutive comments are joined by a new line

Proved by: lang-sql/suite/docs.test.ts

Tests: passed: suite/docs.test.ts the text of a comment has its markers taken off, whatever kind of comment the dialect has,

Cited by: extensions/docs/text, Lang Sql

FR-002checkpassing

The documentation of a declaration MUST be its leading comments (those on lines of their own that stand directly before it, with no blank line between) followed by its trailing comments (those on its line, after it); the comments that trail the declaration's name (CREATE TABLE t ( -- the table) count as its trailing comments; a detached comment, a dangling one and a comment of another node MUST NOT be part of it; where it has none, it has no documentation.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/docs.test.ts: a declaration is documented by its leading comments, its trailing comments and those that trail its name, and by no detached, dangling or other comment

Proved by: lang-sql/suite/docs.test.ts

Tests: passed: suite/docs.test.ts a declaration is documented by its leading comments, its trailing comments and those that

Cited by: extensions/docs/declarations, Lang Sql

What it says

FR-003checkpassing

parseDoc MUST give a summary (the first paragraph, with its lines joined by a space), a description (the paragraphs after it that come before the first tag, with their line breaks kept) and the tags; a tag MUST begin on a line whose first character is @ followed by a name, and its text MUST continue over the lines that follow until the next tag; an empty paragraph, text that begins with a tag, and a tag with no text MUST be allowed.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/docs.test.ts: documentation has a summary, a description and tags, read as TSDoc reads them

Proved by: lang-sql/suite/docs.test.ts

Tests: passed: suite/docs.test.ts documentation has a summary, a description and tags, read as TSDoc reads them

Cited by: extensions/docs/doc, Lang Sql

FR-004checkpassing

The tags param (a name, an optional type in braces, and its text), returns (and return), example, deprecated, since and see MUST be typed; every other tag MUST be a tag with its name and text; and a project MUST be able to give a reader for a tag of its own, which is used in the place of the generic one.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/docs.test.ts: param, returns, example, deprecated, since and see are typed, every other tag is a tag with its name and text, and a project's reader is used in the place of the generic one

Proved by: lang-sql/suite/docs.test.ts

Tests: passed: suite/docs.test.ts param, returns, example, deprecated, since and see are typed, every other tag is a tag wit

Cited by: extensions/docs/doc

FR-005checkpassing

The code of an example MUST be the text of the tag with a Markdown fence ( ` or `sql ) taken off where it has one, and MUST be parsed with the dialect of the script, so that the example's tree and its errors are part of the tag.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/docs.test.ts: the code of an example is the text of the tag without its fence, parsed with the dialect of the script, with its tree and errors

Proved by: lang-sql/suite/docs.test.ts

Tests: passed: suite/docs.test.ts the code of an example is the text of the tag without its fence, parsed with the dialect o

Cited by: extensions/docs/doc, Lang Sql

What is documented

FR-006checkpassing

documentScript MUST give, in the order of the text, a declaration for each of: a table (create-table), with its columns and its named constraints as members; a view; an index; each common table expression of a WITH; a column added by ALTER TABLE ... ADD COLUMN; and every other statement, so that a named query can be documented; each with its kind, its name as written (qualified names joined by a dot), its node and its documentation or none.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/docs.test.ts: a script gives, in order, its tables with columns and named constraints, views, indexes, common table expressions, added columns and other statements, each with its kind, name, node and documentation

Proved by: lang-sql/suite/docs.test.ts

Tests: passed: suite/docs.test.ts a script gives, in order, its tables with columns and named constraints, views, indexes, c

Cited by: extensions/docs/declarations, Lang Sql

FR-007checkpassing

toMarkdown MUST write declarations as Markdown, one section for each declaration with a documentation or members, in the order of the text: the heading is the kind and the name, then the summary and description, a list of the members with their summaries, and each tag, with the examples as fenced code; and it MUST write the same text for the same declarations.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/docs.test.ts: declarations are written as Markdown, one section for each that has documentation or members that have it, with the same text for the same declarations

Proved by: lang-sql/suite/docs.test.ts

Tests: passed: suite/docs.test.ts declarations are written as Markdown, one section for each that has documentation or membe

Cited by: extensions/docs/markdown, Lang Sql

FR-008checkpassing

Extracting documentation MUST NOT change the tree, the comments or the attachments it reads, and MUST give the same result for the same input.

Enforced (check): .github: cd commons/lang-sql && bun run verify — suite/docs.test.ts: extracting documentation changes nothing it reads and gives the same result for the same input

Proved by: lang-sql/suite/docs.test.ts

Tests: passed: suite/docs.test.ts extracting documentation changes nothing it reads and gives the same result for the same i

Out of scope

  • Documentation of routines and of what a routine's body holds: a later specification, with the parsers of stored routines.
  • Resolving @see to a declaration, checking that a @param names a parameter, and generating a site.

Edge cases

  • A column that has a comment on the line above it and another after it on its line: the documentation is both, in that order, per FR-002.
  • A comment above a table separated from it by a blank line: no documentation, per FR-002.
  • /** @deprecated use b */ over a column: no summary, a deprecated tag, per FR-003.
  • A @param with no type: the type is absent, per FR-004.
  • @example followed by a fenced block that holds two statements: both are parsed, per FR-005.
  • -- name: GetUser :one before a query: the documentation of that statement, whose text is that line, per FR-006.

Assumptions

  • The first paragraph is the summary, as in TSDoc; no sentence is cut.
  • A comment that is not meant as documentation (a commented-out statement) is documentation to this feature; telling them apart is the project's convention.

Open questions

OQ-1open question

Whether trailing comments of a table (after its closing parenthesis) should be documentation of the table; they are, per FR-002, as they are comments of the node.

Key entities

  • Doc - a summary, a description and tags.
  • Declaration - a documented part of a script with its members.

Success criteria

SC-001success criterion

The comments a person wrote beside the tables and columns of a schema come out as structured documentation in any dialect and with any kind of comment.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

extensions/docs/declarations, extensions/docs/doc, extensions/docs/markdown, extensions/docs/text, Lang Sql

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