Skip to content

Understanding documentation coverage

This page explains the mental model behind the comments analyzer: what documentation coverage means, how the analyzer distinguishes comment types, and what a healthy comment density looks like. For configuration keys and the output schema, see the Comments reference.

What it measures

The comments analyzer evaluates documentation coverage by examining comment presence, placement, and density across your source code. It identifies functions and classes that lack documentation and measures overall documentation quality.

Documentation coverage

The percentage of public functions, methods, and classes that have an associated documentation comment. A comment is "associated" when it immediately precedes the declaration.

Comment placement quality

Not all comments are equally useful. The analyzer distinguishes:

  • Doc comments: Comments immediately before a function/class declaration
  • Inline comments: Comments within function bodies
  • Orphan comments: Comments not associated with any code structure

Comment density

The ratio of comment lines to total lines of code. Provides a quick overall measure of how well-documented a file is.

Healthy ratios

A comment density between 15-30% is generally considered healthy. Below 10% suggests under-documentation; above 40% may indicate stale or redundant comments.

Use cases

  • Documentation enforcement: Require minimum documentation coverage in CI/CD pipelines.
  • Onboarding assessment: Measure how well-documented a codebase is before new team members join.
  • API surface quality: Ensure all exported/public functions have doc comments.
  • Stale comment detection: Identify files with unusually high comment density that may contain outdated comments.

Limitations

  • Comment quality: The analyzer measures comment presence and placement, not comment quality. A comment saying // do the thing counts the same as a thorough description.
  • Language conventions: Documentation comment conventions vary by language (e.g., /// in Rust, """ in Python, // in Go). The UAST normalizes these, but edge cases in less common languages may be missed.
  • Auto-generated docs: Comments generated by tools (e.g., protobuf stubs) are counted the same as hand-written documentation.
  • Multilingual comments: Comment text is not analyzed for language quality or correctness.

See also