IF Commons GitHub

physical/sources/comments

Written to: 1 requirement: 0 proved, 0 partly, 0 failing, 1 with no test recorded. 0004-planning-sources FR-009

The source for comments in source files (0037-planning FR-027): a comment that carries one of the markers set in the configuration (TODO, FIXME, XXX and HACK by default, the markers the documentation scan of Docs reads) is an item of the kind todo, with the fingerprint of the comment's normalized text, the symbol that encloses it and its place among equal ones there, so that the id survives a move of the line inside the file; the anchor MARKER(#id) in the comment is the id of its item. The only thing written is that anchor, only in the files the configuration lists and never in a generated or a vendored file.

The reader knows the comment syntax of a file by its extension (// and block comments for the C family, # and -- for scripts and SQL) and skips string literals on a line. The enclosing symbol is the nearest declaration above the comment that is indented less than it (a function, class, type, constant or method by the keywords of the common languages): a heuristic and not a parser, so a comment between two functions of one indent has the symbol of neither. A comment with no text after its marker reads with the marker as its title.

import { commentsLens } from "./comments.ts";
commentsLens({ anchorFiles: (p) => p.startsWith("src/") }).name; // "comments"

Source: commons/planning/src/physical/sources/comments.ts

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

physical.CommentsConfigtypeno test imports it
type CommentsConfig = {
  /** The markers read (`TODO`, `FIXME`, `XXX`, `HACK` where none). */
  readonly markers?: readonly string[];
  /** The files an anchor may be written to; none where it is left out, so that nothing is written. */
  readonly anchorFiles?: (path: string) => boolean;
};

What the configuration says of the comments source.

physical.DEFAULT_MARKERSconstno test imports it
const DEFAULT_MARKERS: readonly string[]

The markers read where the configuration names none.

physical.isGeneratedOrVendoredfunctionno test imports it
function isGeneratedOrVendored(path: string): boolean

Whether a path is a generated or a vendored file: never written to.

physical.Foundtypeno test imports it
type Found = {
  readonly line: number;
  readonly marker: string;
  readonly text: string;
  readonly anchor: ItemId | undefined;
  readonly symbol: string;
  /** The index in the line where the marker begins and ends. */
  readonly markerStart: number;
  readonly markerEnd: number;
  readonly hasAnchor: boolean;
};

A comment with a marker, read from a file.

physical.commentsOffunctionno test imports it
function commentsOf(path: string, text: string, markers: readonly string[]): readonly Found[]

Every comment of a text that carries a marker.

physical.commentsLensfunctionno test imports it
function commentsLens(config?: CommentsConfig): FileLens

The lens for the comments of source files, with the markers and the files an anchor may be written to.

CommentsConfigtypeno test imports it
type CommentsConfig = {
  /** The markers read (`TODO`, `FIXME`, `XXX`, `HACK` where none). */
  readonly markers?: readonly string[];
  /** The files an anchor may be written to; none where it is left out, so that nothing is written. */
  readonly anchorFiles?: (path: string) => boolean;
};

What the configuration says of the comments source.

DEFAULT_MARKERSconstno test imports it
const DEFAULT_MARKERS: readonly string[]

The markers read where the configuration names none.

isGeneratedOrVendoredfunctionno test imports it
function isGeneratedOrVendored(path: string): boolean

Whether a path is a generated or a vendored file: never written to.

Foundtypeno test imports it
type Found = {
  readonly line: number;
  readonly marker: string;
  readonly text: string;
  readonly anchor: ItemId | undefined;
  readonly symbol: string;
  /** The index in the line where the marker begins and ends. */
  readonly markerStart: number;
  readonly markerEnd: number;
  readonly hasAnchor: boolean;
};

A comment with a marker, read from a file.

commentsOffunctionno test imports it
function commentsOf(path: string, text: string, markers: readonly string[]): readonly Found[]

Every comment of a text that carries a marker.

commentsLensfunctionno test imports it
function commentsLens(config?: CommentsConfig): FileLens

The lens for the comments of source files, with the markers and the files an anchor may be written to.

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