DOC003)Table of Contents
This violation code warns you when pydoclint thinks that the docstring is
written in a different style than the style you specified via the --style
config option.
pydoclint detects the style of a docstring with this procedure:
We now rely on lightweight heuristics that look for style-specific keywords at the indentation level where the docstring begins:
Returns + -------), using a curated list of keywords.Args:, Returns:, Yields:,
Raises:, Examples:, or Notes: with matching indentation.:param, :type, :raises,
:return:, :rtype:, :yield:, or :ytype:.Each helper only considers keywords that start at the same indentation level as the opening triple quotes to avoid counting inline roles or nested blocks.
Args: plus Sphinx :param directives), so we emit DOC003 for every
configured style.When DOC003 is triggered we still return the docstring parsed in the configured style, but we suppress many follow-up checks that would otherwise generate cascading false positives (argument type-hint expectations, return/yield/raise consistency, etc.). This keeps the feedback focused on resolving the style mismatch first.
The authors of pydoclint have manually tested this heuristic in 8 repositories written in all 3 styles (numpy, Google, and Sphinx), and have found this heuristic to be satisfactory:
However, we admit that 8 is too small a sample size to be statistically representative. If you encounter any false positives or false negatives, please don’t hesitate to file an issue here.
Actually, this style mismatch detection feature is by default off.
You can turn this feature on by setting --check-style-mismatch (or -csm) to
True (or --check-style-mismatch=True).
No. The new detection flow usually parses at most one style per docstring, but even when we fall back to the configured style the cost is still negligible. For reference, benchmarking large code bases (as of 2025/01/12) shows the overhead of style detection is only a few percent:
| numpy | scikit-learn | Bokeh | Airflow | |
|---|---|---|---|---|
| Number of .py files | 581 | 929 | 1196 | 5004 |
| Run time with 1 style [sec] | 1.84 | 2.68 | 0.77 | 5.50 |
| Run time with 3 styles [sec] | 1.91 | 2.79 | 0.78 | 5.77 |
| Additional run time [sec] | 0.07 | 0.11 | 0.01 | 0.07 |
| Relative additional run time | 4% | 4% | 1% | 5% |
DOC003: “Docstring style mismatch”.
You are suggested to check if the docstring style is consistent with what you
specified via the --style config option. If not, please rewrite your
docstring, or specify the correct style via --style.
Also, please note that specifying an incorrect docstring style may mask other violations. So after you fix the docstring style, you may need to fix other “new” (previously hidden) violations.