0
# Command Line Interface
1

2
Complete command-line tool for docstring linting with extensive configuration options, style detection, and baseline management for gradual adoption in large codebases.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
The primary command-line interface for pydoclint with comprehensive configuration options for all aspects of docstring validation.
9

10
```python { .api }
11
def main(
12
    ctx: click.Context,
13
    quiet: bool,
14
    exclude: str,
15
    style: str,
16
    paths: tuple[str, ...],
17
    type_hints_in_signature: str,
18
    type_hints_in_docstring: str,
19
    arg_type_hints_in_signature: bool,
20
    arg_type_hints_in_docstring: bool,
21
    check_arg_order: bool,
22
    skip_checking_short_docstrings: bool,
23
    skip_checking_raises: bool,
24
    allow_init_docstring: bool,
25
    check_return_types: bool,
26
    check_yield_types: bool,
27
    ignore_underscore_args: bool,
28
    ignore_private_args: bool,
29
    check_class_attributes: bool,
30
    should_document_private_class_attributes: bool,
31
    treat_property_methods_as_class_attributes: bool,
32
    require_return_section_when_returning_none: bool,
33
    require_return_section_when_returning_nothing: bool,
34
    require_yield_section_when_yielding_nothing: bool,
35
    only_attrs_with_classvar_are_treated_as_class_attrs: bool,
36
    should_document_star_arguments: bool,
37
    should_declare_assert_error_if_assert_statement_exists: bool,
38
    check_style_mismatch: bool,
39
    check_arg_defaults: bool,
40
    generate_baseline: bool,
41
    auto_regenerate_baseline: bool,
42
    baseline: str,
43
    show_filenames_in_every_violation_message: bool,
44
    config: str | None,
45
) -> None:
46
    """
47
    Command-line entry point of pydoclint.
48
    
49
    Validates Python docstrings against function signatures and implementations
50
    with extensive configuration options for all validation rules.
51
    
52
    Parameters:
53
    - ctx: Click context for command-line processing
54
    - quiet: If True, suppress file processing output
55
    - exclude: Regex pattern to exclude files/folders
56
    - style: Docstring style ('numpy', 'google', 'sphinx')
57
    - paths: File/directory paths to check
58
    - arg_type_hints_in_signature: Require type hints in function signatures
59
    - arg_type_hints_in_docstring: Require type hints in docstring arguments
60
    - check_arg_order: Validate argument order consistency
61
    - skip_checking_short_docstrings: Skip validation for short summary-only docstrings
62
    - skip_checking_raises: Skip validation of raises sections
63
    - allow_init_docstring: Allow both __init__ and class docstrings
64
    - check_return_types: Validate return type consistency
65
    - check_yield_types: Validate yield type consistency
66
    - ignore_underscore_args: Ignore underscore arguments (_, __, etc.)
67
    - ignore_private_args: Ignore private arguments (leading underscore)
68
    - check_class_attributes: Validate class attributes against docstrings
69
    - should_document_private_class_attributes: Require private class attrs in docs
70
    - treat_property_methods_as_class_attributes: Treat @property as class attributes
71
    - require_return_section_when_returning_nothing: Require return section for None returns
72
    - require_yield_section_when_yielding_nothing: Require yields section for None yields
73
    - only_attrs_with_classvar_are_treated_as_class_attrs: Only ClassVar attrs as class attrs
74
    - should_document_star_arguments: Require *args/**kwargs in docstrings
75
    - should_declare_assert_error_if_assert_statement_exists: Declare AssertionError for asserts
76
    - check_style_mismatch: Validate style consistency within docstrings
77
    - check_arg_defaults: Validate default values in docstring type hints
78
    - generate_baseline: Generate new baseline file
79
    - auto_regenerate_baseline: Automatically update baseline when violations fixed
80
    - baseline: Path to baseline file for tracking existing violations
81
    - show_filenames_in_every_violation_message: Include filename in each violation
82
    - config: Path to TOML configuration file
83
    
84
    Returns:
85
    None (exits with status code 0 for success, 1 for violations found)
86
    """
87
```
88

89
### Style Validation
90

91
Validates that the specified docstring style is one of the supported formats.
92

93
```python { .api }
94
def validateStyleValue(
95
    context: click.Context,
96
    param: click.Parameter,
97
    value: str | None,
98
) -> str | None:
99
    """
100
    Validate the value of the 'style' option.
101
    
102
    Parameters:
103
    - context: Click context object
104
    - param: Click parameter object
105
    - value: Style value to validate
106
    
107
    Returns:
108
    str | None: Validated style value
109
    
110
    Raises:
111
    click.BadParameter: If style is not 'numpy', 'google', or 'sphinx'
112
    """
113
```
114

115
### Path Processing
116

117
Internal functions for processing multiple paths and individual files.
118

119
```python { .api }
120
def _checkPaths(
121
    paths: tuple[str, ...],
122
    style: str = 'numpy',
123
    argTypeHintsInSignature: bool = True,
124
    argTypeHintsInDocstring: bool = True,
125
    checkArgOrder: bool = True,
126
    skipCheckingShortDocstrings: bool = True,
127
    skipCheckingRaises: bool = False,
128
    allowInitDocstring: bool = False,
129
    checkReturnTypes: bool = True,
130
    checkYieldTypes: bool = True,
131
    ignoreUnderscoreArgs: bool = True,
132
    ignorePrivateArgs: bool = False,
133
    checkClassAttributes: bool = True,
134
    shouldDocumentPrivateClassAttributes: bool = False,
135
    treatPropertyMethodsAsClassAttributes: bool = False,
136
    onlyAttrsWithClassVarAreTreatedAsClassAttrs: bool = False,
137
    requireReturnSectionWhenReturningNothing: bool = False,
138
    requireYieldSectionWhenYieldingNothing: bool = False,
139
    shouldDocumentStarArguments: bool = True,
140
    shouldDeclareAssertErrorIfAssertStatementExists: bool = False,
141
    checkStyleMismatch: bool = False,
142
    checkArgDefaults: bool = False,
143
    quiet: bool = False,
144
    exclude: str = '',
145
) -> dict[str, list[Violation]]:
146
    """
147
    Check multiple file/directory paths for docstring violations.
148
    
149
    Parameters:
150
    - paths: Tuple of file/directory paths to check
151
    - style: Docstring style to validate against
152
    - (additional parameters match main function)
153
    
154
    Returns:
155
    dict[str, list[Violation]]: Mapping of file paths to their violations
156
    """
157

158
def _checkFile(
159
    filename: Path,
160
    style: str = 'numpy',
161
    argTypeHintsInSignature: bool = True,
162
    argTypeHintsInDocstring: bool = True,
163
    checkArgOrder: bool = True,
164
    skipCheckingShortDocstrings: bool = True,
165
    skipCheckingRaises: bool = False,
166
    allowInitDocstring: bool = False,
167
    checkReturnTypes: bool = True,
168
    checkYieldTypes: bool = True,
169
    ignoreUnderscoreArgs: bool = True,
170
    ignorePrivateArgs: bool = False,
171
    checkClassAttributes: bool = True,
172
    shouldDocumentPrivateClassAttributes: bool = False,
173
    treatPropertyMethodsAsClassAttributes: bool = False,
174
    onlyAttrsWithClassVarAreTreatedAsClassAttrs: bool = False,
175
    requireReturnSectionWhenReturningNothing: bool = False,
176
    requireYieldSectionWhenYieldingNothing: bool = False,
177
    shouldDocumentStarArguments: bool = True,
178
    shouldDeclareAssertErrorIfAssertStatementExists: bool = False,
179
    checkStyleMismatch: bool = False,
180
    checkArgDefaults: bool = False,
181
) -> list[Violation]:
182
    """
183
    Check a single Python file for docstring violations.
184
    
185
    Parameters:
186
    - filename: Path to Python file to check
187
    - (additional parameters match main function)
188
    
189
    Returns:
190
    list[Violation]: List of violations found in the file
191
    """
192
```
193

194
## Usage Examples
195

196
### Basic Usage
197

198
```python
199
# Check current directory with numpy style
200
pydoclint .
201

202
# Check specific files with google style
203
pydoclint --style=google src/module.py src/utils.py
204

205
# Quiet mode with custom exclusions
206
pydoclint --quiet --exclude="tests/|migrations/" src/
207
```
208

209
### Advanced Configuration
210

211
```python
212
# Comprehensive checking with all features enabled
213
pydoclint \
214
    --style=numpy \
215
    --check-class-attributes=True \
216
    --check-return-types=True \
217
    --check-yield-types=True \
218
    --should-document-star-arguments=True \
219
    --check-style-mismatch=True \
220
    src/
221

222
# Gradual adoption with baseline
223
pydoclint --generate-baseline --baseline=current-violations.txt src/
224
pydoclint --baseline=current-violations.txt --auto-regenerate-baseline=True src/
225
```
226

227
### Configuration File Usage
228

229
```python
230
# Use custom configuration file
231
pydoclint --config=custom-config.toml src/
232

233
# Configuration in pyproject.toml
234
[tool.pydoclint]
235
style = 'google'
236
exclude = '\.git|tests/'
237
check-class-attributes = true
238
require-return-section-when-returning-nothing = true
239
```