Skip to content

Documentation Coverage

Measures the extent to which code elements (classes, methods, functions, etc.) are documented with comments or documentation strings.

What it Measures

Percentage of code elements that have associated documentation comments.

How it's Measured

  • Identify code elements such as classes, methods, functions, and modules.
  • Check for the presence of documentation comments (e.g., docstrings, Javadoc-style comments).
  • Calculate the ratio of documented elements to the total number of elements.

Why it Helps

  • Encourages better documentation practices.
  • Improves code maintainability and readability.

Communicate Intent

Coverage measures where docs exist; usefulness depends on what they say. Good docstrings answer: what does this do, how do I use it, and what are the surprises or edge cases? Prioritize public APIs and anything that users might need to import implicitly. Document public types/methods, especially at library boundaries and implicit/given instances.

1. Document a public API

A few lines prevent hours of guesswork. The example anchors expectations; the thrown exception clarifies failure modes. Keep comments close to code so they travel with refactors.

def parse(s: String): Result

/** Parses a DSL document from UTF-8 text.
  * @param s full document text
  * @return a parsed result; errors include 1-based line/column
  */
def parse(s: String): Result

2. Explain givens/instances

Context parameters and conversions are invisible at call sites. Documentation is your primary defense against surprise.

/** Low-priority fallback instances for JSON encoding. */
given fallbackEncoder: Encoder[Foo] = ???

Tip

Keep docstrings short, but answer: what, when to use, and surprises.

3. Keep docs alive

Make it easy to update docs during code changes: short, local comments, doc tests, pre‑commit hooks that lint stale references. Coverage is the dashboard, but the habit is what keeps readers happy.