commentsare

Commentsare is a proposed framework for standardizing the way documentation comments are written, parsed, and used across programming languages and content formats. It treats comments as structured, machine-readable annotations in addition to human-readable notes, with the aim of improving documentation generation, code navigation, and static analysis. The concept appears in theoretical discussions and experimental tooling rather than as an official language specification.

Concepts and goals

Its core ideas include structured blocks within comments that carry metadata such as type, severity or level, and identifiers; a language-agnostic or easily adaptable syntax; mechanisms to associate comments with specific code elements through unique IDs; and tooling that can extract, index, validate, and render documentation from these annotated comments. Proponents emphasize interoperability across diverse languages and integration with existing documentation ecosystems.

Structure and syntax

A language-agnostic example of a Commentsare block might include fields such as version, kind or type, id, description, and optional tags or references. For instance, a block could specify version: 1, kind: note, id: funcX-101, description: "Explains the purpose of functionX," along with tags like architecture or example and references to external documentation. Implementations typically provide adapters to convert these blocks into conventional docs formats or to feed them into documentation generators and IDEs.

Tooling and adoption

Supportive tooling would include linters that enforce consistency, parsers that extract blocks for indexing, and documentation generators that render the comments into human- and machine-readable outputs. Adoption remains limited and fragmented, with concerns about complexity, learning curve, backward compatibility, and performance overhead when parsing large codebases.

See also

Inline documentation, docstrings, literate programming, code documentation standards such as JSDoc and reStructuredText.