We define documentation coverage as the number of scopes that have some sort of documentation added, versus the number of scopes (classes, functions, structs, modules) that exist in a given codebase.
Take, for example, a hypothetical Python codebase, which consists of only one file, named 42.py.
42.py
"""
This module contains the answer to life, universe and everything.
"""
def answer():
return 42
def question():
"""
This function returns the question wrt the answer to life,
universe and everything.
"""
raise NotImplementedError
In the example above, there are 2 functions, of which one contains documentation. There is also a file, which actually contains all of this code. Hence, there are 3 scopes in this codebase: 2 functions and a file. Since documentation coverage is (documented_scopes/total_number_of_scopes) * 100, the documentation coverage for the above code will be 66.6%.
What is test documentation coverage?
The test documentation coverage only displays the documentation coverage in test files, while application documentation coverage displays the documentation coverage for all files except test files.
What is API documentation coverage?
In Go repositories, there is an additional metric named API documentation coverage, which only displays the documentation coverage for exported names.
I do not want to include file-level documentation in my coverage report. Is it possible?
The documentation coverage calculator can be configured to exclude/include some scopes. Details can be found here:
Python: https://deepsource.io/docs/analyzer/python.html#skip-doc-coverage
Go: https://deepsource.io/docs/analyzer/go.html#skip-doc-coverage