The source for comments in source files (0037-planningFR-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.
typeCommentsConfig= {
/** The markers read (`TODO`, `FIXME`, `XXX`, `HACK` where none). */readonlymarkers?:readonlystring[];
/** The files an anchor may be written to; none where it is left out, so that nothing is written. */readonlyanchorFiles?: (path:string) =>boolean;
};
What the configuration says of the comments source.
typeFound= {
readonlyline:number;
readonlymarker:string;
readonlytext:string;
readonlyanchor:ItemId|undefined;
readonlysymbol:string;
/** The index in the line where the marker begins and ends. */readonlymarkerStart:number;
readonlymarkerEnd:number;
readonlyhasAnchor:boolean;
};
typeCommentsConfig= {
/** The markers read (`TODO`, `FIXME`, `XXX`, `HACK` where none). */readonlymarkers?:readonlystring[];
/** The files an anchor may be written to; none where it is left out, so that nothing is written. */readonlyanchorFiles?: (path:string) =>boolean;
};
What the configuration says of the comments source.
typeFound= {
readonlyline:number;
readonlymarker:string;
readonlytext:string;
readonlyanchor:ItemId|undefined;
readonlysymbol:string;
/** The index in the line where the marker begins and ends. */readonlymarkerStart:number;
readonlymarkerEnd:number;
readonlyhasAnchor:boolean;
};