Add config option to skip private functions

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change Log
 
+## [0.8.4] - 2026-3-13
+
+- Added
+  - A new config option `--skip-checking-private-functions` (shortform:
+    `-scpf`) so docstrings in private methods can be skipped
+- Full diff
+  - https://github.com/jsh9/pydoclint/compare/0.8.3...0.8.4
+
 ## [0.8.3] - 2025-11-26
 
 - Added

docs/config_options.md

@@ -20,27 +20,28 @@ ______________________________________________________________________
 - [5. `--check-arg-order` (shortform: `-ao`, default: `True`)](#5---check-arg-order-shortform--ao-default-true)
 - [6. `--skip-checking-short-docstrings` (shortform: `-scsd`, default: `True`)](#6---skip-checking-short-docstrings-shortform--scsd-default-true)
 - [7. `--skip-checking-raises` (shortform: `-scr`, default: `False`)](#7---skip-checking-raises-shortform--scr-default-false)
-- [8. `--allow-init-docstring` (shortform: `-aid`, default: `False`)](#8---allow-init-docstring-shortform--aid-default-false)
-- [9. `--require-return-section-when-returning-nothing` (shortform: `-rrs`, default: `False`)](#9---require-return-section-when-returning-nothing-shortform--rrs-default-false)
-- [10. `--check-return-types` (shortform: `-crt`, default: `True`)](#10---check-return-types-shortform--crt-default-true)
-- [11. `--require-yield-section-when-yielding-nothing` (shortform: `-rys`, default: `True`)](#11---require-yield-section-when-yielding-nothing-shortform--rys-default-true)
-- [12. `--check-yield-types` (shortform: `-cyt`, default: `True`)](#12---check-yield-types-shortform--cyt-default-true)
-- [13. `--ignore-underscore-args` (shortform: `-iua`, default: `True`)](#13---ignore-underscore-args-shortform--iua-default-true)
-- [14. `--ignore-private-args` (shortform: `-ipa`, default: `False`)](#14---ignore-private-args-shortform--ipa-default-false)
-- [15. `--check-class-attributes` (shortform: `-cca`, default: `True`)](#15---check-class-attributes-shortform--cca-default-true)
-- [16. `--should-document-private-class-attributes` (shortform: `-sdpca`, default: `False`)](#16---should-document-private-class-attributes-shortform--sdpca-default-false)
-- [17. `--treat-property-methods-as-class-attributes` (shortform: `-tpmaca`, default: `False`)](#17---treat-property-methods-as-class-attributes-shortform--tpmaca-default-false)
-- [18. `--only-attrs-with-ClassVar-are-treated-as-class-attrs` (shortform: `-oawcv`, default: `False`)](#18---only-attrs-with-classvar-are-treated-as-class-attrs-shortform--oawcv-default-false)
-- [19. `--should-document-star-arguments` (shortform: `-sdsa`, default: `True`)](#19---should-document-star-arguments-shortform--sdsa-default-true)
-- [20. `--omit-stars-when-documenting-varargs` (shortform: `-oswdv`, default: `False`)](#20---omit-stars-when-documenting-varargs-shortform--oswdv-default-false)
-- [21. `--check-style-mismatch` (shortform: `-csm`, default: `False`)](#21---check-style-mismatch-shortform--csm-default-false)
-- [22. `--check-arg-defaults` (shortform: `-cad`, default: `False`)](#22---check-arg-defaults-shortform--cad-default-false)
-- [23. `--baseline`](#23---baseline)
-- [24. `--generate-baseline` (default: `False`)](#24---generate-baseline-default-false)
-- [25. `--auto-regenerate-baseline` (shortform: `-arb`, default: `True`)](#25---auto-regenerate-baseline-shortform--arb-default-true)
-- [26. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)](#26---show-filenames-in-every-violation-message-shortform--sfn-default-false)
-- [27. `--native-mode-noqa-location` (shortform: `-nmnl`, default: `docstring`)](#27---native-mode-noqa-location-shortform--nmnl-default-docstring)
-- [28. `--config` (default: `pyproject.toml`)](#28---config-default-pyprojecttoml)
+- [8. `--skip-checking-private-functions` (shortform: `-scpf`, default: `False`)](#8---skip-checking-private-functions-shortform--scpf-default-false)
+- [9. `--allow-init-docstring` (shortform: `-aid`, default: `False`)](#9---allow-init-docstring-shortform--aid-default-false)
+- [10. `--require-return-section-when-returning-nothing` (shortform: `-rrs`, default: `False`)](#10---require-return-section-when-returning-nothing-shortform--rrs-default-false)
+- [11. `--check-return-types` (shortform: `-crt`, default: `True`)](#11---check-return-types-shortform--crt-default-true)
+- [12. `--require-yield-section-when-yielding-nothing` (shortform: `-rys`, default: `True`)](#12---require-yield-section-when-yielding-nothing-shortform--rys-default-true)
+- [13. `--check-yield-types` (shortform: `-cyt`, default: `True`)](#13---check-yield-types-shortform--cyt-default-true)
+- [14. `--ignore-underscore-args` (shortform: `-iua`, default: `True`)](#14---ignore-underscore-args-shortform--iua-default-true)
+- [15. `--ignore-private-args` (shortform: `-ipa`, default: `False`)](#15---ignore-private-args-shortform--ipa-default-false)
+- [16. `--check-class-attributes` (shortform: `-cca`, default: `True`)](#16---check-class-attributes-shortform--cca-default-true)
+- [17. `--should-document-private-class-attributes` (shortform: `-sdpca`, default: `False`)](#17---should-document-private-class-attributes-shortform--sdpca-default-false)
+- [18. `--treat-property-methods-as-class-attributes` (shortform: `-tpmaca`, default: `False`)](#18---treat-property-methods-as-class-attributes-shortform--tpmaca-default-false)
+- [19. `--only-attrs-with-ClassVar-are-treated-as-class-attrs` (shortform: `-oawcv`, default: `False`)](#19---only-attrs-with-classvar-are-treated-as-class-attrs-shortform--oawcv-default-false)
+- [20. `--should-document-star-arguments` (shortform: `-sdsa`, default: `True`)](#20---should-document-star-arguments-shortform--sdsa-default-true)
+- [21. `--omit-stars-when-documenting-varargs` (shortform: `-oswdv`, default: `False`)](#21---omit-stars-when-documenting-varargs-shortform--oswdv-default-false)
+- [22. `--check-style-mismatch` (shortform: `-csm`, default: `False`)](#22---check-style-mismatch-shortform--csm-default-false)
+- [23. `--check-arg-defaults` (shortform: `-cad`, default: `False`)](#23---check-arg-defaults-shortform--cad-default-false)
+- [24. `--baseline`](#24---baseline)
+- [25. `--generate-baseline` (default: `False`)](#25---generate-baseline-default-false)
+- [26. `--auto-regenerate-baseline` (shortform: `-arb`, default: `True`)](#26---auto-regenerate-baseline-shortform--arb-default-true)
+- [27. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)](#27---show-filenames-in-every-violation-message-shortform--sfn-default-false)
+- [28. `--native-mode-noqa-location` (shortform: `-nmnl`, default: `docstring`)](#28---native-mode-noqa-location-shortform--nmnl-default-docstring)
+- [29. `--config` (default: `pyproject.toml`)](#29---config-default-pyprojecttoml)
 
 ______________________________________________________________________
 
@@ -156,7 +157,14 @@ If `True`, _pydoclint_ won't report `DOC501` or `DOC502` if there are `raise`
 statements in the function/method but there aren't any "raises" sections in the
 docstring (or vice versa).
 
-## 8. `--allow-init-docstring` (shortform: `-aid`, default: `False`)
+## 8. `--skip-checking-private-functions` (shortform: `-scpf`, default: `False`)
+
+If `True`, _pydoclint_ won't check functions that are private. This includes
+all methods with names that start with '`_`' but not methods whose names start
+and end with '`__`' (dunder methods). Any methods defined within private
+methods are also skipped.
+
+## 9. `--allow-init-docstring` (shortform: `-aid`, default: `False`)
 
 If it is set to `True`, having a docstring for class constructors
 (`__init__()`) is allowed, and the arguments are expected to be documented
@@ -166,43 +174,43 @@ Note: the default is set to `False` because not every class has an `__init__`
 method (such as classes that inherit from parent classes), but every class must
 have the `class ClassName` declaration.
 
-## 9. `--require-return-section-when-returning-nothing` (shortform: `-rrs`, default: `False`)
+## 10. `--require-return-section-when-returning-nothing` (shortform: `-rrs`, default: `False`)
 
 If `False`, a "return" section is not necessary in the docstring if the
 function implicitly returns `None` (for example, doesn't have a return
 statement, or has `-> None` as the return annotation) or doesn't return at all
 (has return type `NoReturn`).
 
-## 10. `--check-return-types` (shortform: `-crt`, default: `True`)
+## 11. `--check-return-types` (shortform: `-crt`, default: `True`)
 
 If True, check that the type(s) in the docstring return section and the return
 annotation in the function signature are consistent
 
-## 11. `--require-yield-section-when-yielding-nothing` (shortform: `-rys`, default: `True`)
+## 12. `--require-yield-section-when-yielding-nothing` (shortform: `-rys`, default: `True`)
 
 If False, a yields section is not needed in docstring if the function yields
 None.
 
-## 12. `--check-yield-types` (shortform: `-cyt`, default: `True`)
+## 13. `--check-yield-types` (shortform: `-cyt`, default: `True`)
 
 If True, check that the type(s) in the docstring "yields" section and the
 return annotation in the function signature are consistent.
 
-## 13. `--ignore-underscore-args` (shortform: `-iua`, default: `True`)
+## 14. `--ignore-underscore-args` (shortform: `-iua`, default: `True`)
 
 If True, underscore arguments (such as \_, \_\_, ...) in the function signature
 do not need to appear in the docstring.
 
 Note: "underscore arguments" are not the same as "private arguments" (i.e.,
 "arguments with leading underscores") such as `_a`.
 
-## 14. `--ignore-private-args` (shortform: `-ipa`, default: `False`)
+## 15. `--ignore-private-args` (shortform: `-ipa`, default: `False`)
 
 If True, private arguments (those with leading underscores in their names but
 are not purely `_`, `__`, etc.) in the function signature do not need to appear
 in the docstring.
 
-## 15. `--check-class-attributes` (shortform: `-cca`, default: `True`)
+## 16. `--check-class-attributes` (shortform: `-cca`, default: `True`)
 
 If True, check the class attributes (defined under the class definition)
 against the "Attributes" section of the class's docstring.
@@ -211,38 +219,38 @@ Please read
 [this page](https://jsh9.github.io/pydoclint/checking_class_attributes.html)
 for more instructions.
 
-## 16. `--should-document-private-class-attributes` (shortform: `-sdpca`, default: `False`)
+## 17. `--should-document-private-class-attributes` (shortform: `-sdpca`, default: `False`)
 
 If True, private class attributes (those that start with leading `_`) should be
 documented. If False, they should not be documented.
 
-## 17. `--treat-property-methods-as-class-attributes` (shortform: `-tpmaca`, default: `False`)
+## 18. `--treat-property-methods-as-class-attributes` (shortform: `-tpmaca`, default: `False`)
 
 If True, treat `@property` methods as class properties. This means that they
 need to be documented in the "Attributes" section of the class docstring, and
 there cannot be any docstring under the @property methods. This option is only
 effective when --check-class-attributes is True.
 
-## 18. `--only-attrs-with-ClassVar-are-treated-as-class-attrs` (shortform: `-oawcv`, default: `False`)
+## 19. `--only-attrs-with-ClassVar-are-treated-as-class-attrs` (shortform: `-oawcv`, default: `False`)
 
 If True, only the attributes whose type annotations are wrapped within
 `ClassVar` (where `ClassVar` is imported from `typing`) are treated as class
 attributes, and all other attributes are treated as instance attributes.
 
-## 19. `--should-document-star-arguments` (shortform: `-sdsa`, default: `True`)
+## 20. `--should-document-star-arguments` (shortform: `-sdsa`, default: `True`)
 
 If True, "star arguments" (such as `*args`, `**kwargs`, `**props`, etc.) in the
 function signature should be documented in the docstring. If False, they should
 not appear in the docstring.
 
-## 20. `--omit-stars-when-documenting-varargs` (shortform: `-oswdv`, default: `False`)
+## 21. `--omit-stars-when-documenting-varargs` (shortform: `-oswdv`, default: `False`)
 
 If True, docstring argument entries describing `*args` or `**kwargs` may omit
 the leading `*`, and pydoclint will still match them against the function
 signature. Leave this disabled to require docstrings to include the leading `*`
 characters for varargs.
 
-## 21. `--check-style-mismatch` (shortform: `-csm`, default: `False`)
+## 22. `--check-style-mismatch` (shortform: `-csm`, default: `False`)
 
 If True, check that style specified in --style matches the detected style of
 the docstring. If there is a mismatch, `DOC003` will be reported. Setting this
@@ -251,13 +259,13 @@ to False will silence all `DOC003` violations.
 Read more about this config option and `DOC003` at
 [https://jsh9.github.io/pydoclint/style_mismatch.html](https://jsh9.github.io/pydoclint/style_mismatch.html).
 
-## 22. `--check-arg-defaults` (shortform: `-cad`, default: `False`)
+## 23. `--check-arg-defaults` (shortform: `-cad`, default: `False`)
 
 If True, docstring type hints should contain default values consistent with the
 function signature. If False, docstring type hints should not contain default
 values. (Only applies to numpy style for now.)
 
-## 23. `--baseline`
+## 24. `--baseline`
 
 Baseline allows you to remember the current project state and then show only
 new violations, ignoring old ones. This can be very useful when you'd like to
@@ -279,20 +287,20 @@ If `--generate-baseline` is not passed to _pydoclint_ (the default is `False`),
 _pydoclint_ will read your baseline file, and ignore all violations specified
 in that file.
 
-## 24. `--generate-baseline` (default: `False`)
+## 25. `--generate-baseline` (default: `False`)
 
 Required to use with `--baseline` option. If `True`, generate the baseline file
 that contains all current violations.
 
-## 25. `--auto-regenerate-baseline` (shortform: `-arb`, default: `True`)
+## 26. `--auto-regenerate-baseline` (shortform: `-arb`, default: `True`)
 
 If it's set to True, _pydoclint_ will automatically regenerate the baseline
 file every time you fix violations in the baseline and rerun _pydoclint_.
 
 This saves you from having to manually regenerate the baseline file by setting
 `--generate-baseline=True` and run _pydoclint_.
 
-## 26. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)
+## 27. `--show-filenames-in-every-violation-message` (shortform: `-sfn`, default: `False`)
 
 If False, in the terminal the violation messages are grouped by file names:
 
@@ -326,7 +334,7 @@ This can be convenient if you would like to click on each violation message and
 go to the corresponding line in your IDE. (Note: not all terminal app offers
 this functionality.)
 
-## 27. `--native-mode-noqa-location` (shortform: `-nmnl`, default: `docstring`)
+## 28. `--native-mode-noqa-location` (shortform: `-nmnl`, default: `docstring`)
 
 This option controls where _pydoclint_ looks for inline `# noqa: DOCxxx`
 comments when running in native mode (i.e., outside of Flake8). Two values are
@@ -341,7 +349,7 @@ Only DOC-prefixed violation codes are honored; other codes are ignored by the
 native parser. This setting has no effect in Flake8 mode, which is controlled
 by Flake8's own `noqa` handling.
 
-## 28. `--config` (default: `pyproject.toml`)
+## 29. `--config` (default: `pyproject.toml`)
 
 The full path of the .toml config file that contains the config options. Note
 that the command line options take precedence over the .toml file. Look at this

pydoclint/flake8_entry.py

@@ -103,6 +103,14 @@ def add_options(cls, parser: Any) -> None:  # noqa: D102
                 ' "raise" statements'
             ),
         )
+        parser.add_option(
+            '-scpf',
+            '--skip-checking-private-functions',
+            action='store',
+            default='False',
+            parse_from_config=True,
+            help='If True, skip checking docstrings of private functions.',
+        )
         parser.add_option(
             '-aid',
             '--allow-init-docstring',
@@ -323,6 +331,9 @@ def parse_options(cls, options: Any) -> None:  # noqa: D102
             options.skip_checking_short_docstrings
         )
         cls.skip_checking_raises = options.skip_checking_raises
+        cls.skip_checking_private_functions = (
+            options.skip_checking_private_functions
+        )
         cls.allow_init_docstring = options.allow_init_docstring
         cls.require_return_section_when_returning_none = (
             options.require_return_section_when_returning_none
@@ -396,6 +407,10 @@ def run(self) -> Generator[tuple[int, int, str, Any], None, None]:
             '--skip-checking-raises',
             self.skip_checking_raises,
         )
+        skipCheckingPrivateFunctions = self._bool(
+            '--skip-checking-private-functions',
+            self.skip_checking_private_functions,
+        )
         allowInitDocstring = self._bool(
             '--allow-init-docstring',
             self.allow_init_docstring,
@@ -469,6 +484,7 @@ def run(self) -> Generator[tuple[int, int, str, Any], None, None]:
             checkArgOrder=checkArgOrder,
             skipCheckingShortDocstrings=skipCheckingShortDocstrings,
             skipCheckingRaises=skipCheckingRaises,
+            skipCheckingPrivateFunctions=skipCheckingPrivateFunctions,
             allowInitDocstring=allowInitDocstring,
             requireReturnSectionWhenReturningNothing=(
                 requireReturnSectionWhenReturningNothing

pydoclint/main.py

@@ -151,6 +151,14 @@ def validateNativeModeNoqaLocation(
         ' statements'
     ),
 )
+@click.option(
+    '-scpf',
+    '--skip-checking-private-functions',
+    type=bool,
+    show_default=True,
+    default=False,
+    help='If True, skip checking docstrings of private functions.',
+)
 @click.option(
     '-aid',
     '--allow-init-docstring',
@@ -457,6 +465,7 @@ def main(  # noqa: C901, PLR0915
         check_arg_order: bool,
         skip_checking_short_docstrings: bool,
         skip_checking_raises: bool,
+        skip_checking_private_functions: bool,
         allow_init_docstring: bool,
         check_return_types: bool,
         check_yield_types: bool,
@@ -565,6 +574,7 @@ def main(  # noqa: C901, PLR0915
         checkArgOrder=check_arg_order,
         skipCheckingShortDocstrings=skip_checking_short_docstrings,
         skipCheckingRaises=skip_checking_raises,
+        skipCheckingPrivateFunctions=skip_checking_private_functions,
         allowInitDocstring=allow_init_docstring,
         checkReturnTypes=check_return_types,
         checkYieldTypes=check_yield_types,
@@ -727,6 +737,7 @@ def _checkPaths(
         checkArgOrder: bool = True,
         skipCheckingShortDocstrings: bool = True,
         skipCheckingRaises: bool = False,
+        skipCheckingPrivateFunctions: bool = False,
         allowInitDocstring: bool = False,
         checkReturnTypes: bool = True,
         checkYieldTypes: bool = True,
@@ -783,6 +794,7 @@ def _checkPaths(
             checkArgOrder=checkArgOrder,
             skipCheckingShortDocstrings=skipCheckingShortDocstrings,
             skipCheckingRaises=skipCheckingRaises,
+            skipCheckingPrivateFunctions=skipCheckingPrivateFunctions,
             allowInitDocstring=allowInitDocstring,
             checkReturnTypes=checkReturnTypes,
             checkYieldTypes=checkYieldTypes,
@@ -827,6 +839,7 @@ def _checkFile(
         checkArgOrder: bool = True,
         skipCheckingShortDocstrings: bool = True,
         skipCheckingRaises: bool = False,
+        skipCheckingPrivateFunctions: bool = False,
         allowInitDocstring: bool = False,
         checkReturnTypes: bool = True,
         checkYieldTypes: bool = True,
@@ -878,6 +891,7 @@ def _checkFile(
         checkArgOrder=checkArgOrder,
         skipCheckingShortDocstrings=skipCheckingShortDocstrings,
         skipCheckingRaises=skipCheckingRaises,
+        skipCheckingPrivateFunctions=skipCheckingPrivateFunctions,
         allowInitDocstring=allowInitDocstring,
         checkReturnTypes=checkReturnTypes,
         checkYieldTypes=checkYieldTypes,