google-docstring-parser 0.0.9__tar.gz → 0.0.11__tar.gz

{google_docstring_parser-0.0.9 → google_docstring_parser-0.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-docstring-parser
-Version: 0.0.9
+Version: 0.0.11
 Summary: A lightweight, efficient parser for Google-style Python docstrings that converts them into structured dictionaries.
 Author: Vladimir Iglovikov
 Maintainer: Vladimir Iglovikov
@@ -153,6 +153,10 @@ References:
 
 Each reference is parsed into a dictionary with `description` and `source` keys. URLs in the source are properly handled, ensuring colons in URLs are not confused with the separator colon.
 
+## Short Description (Meta Description)
+
+The checker extracts the **short description** as the first paragraph (up to the first blank line). Multi-line first paragraphs are joined with spaces. This is useful for meta descriptions on documentation sites. SEO best practice: 120-160 characters. Use `min_short_description_length` and `max_short_description_length` to enforce bounds (0 to disable).
+
 ## Pre-commit Hook
 
 This package includes a pre-commit hook that checks if Google-style docstrings in your codebase can be parsed correctly.
@@ -180,6 +184,9 @@ Add a `[tool.docstring_checker]` section to your pyproject.toml:
 paths = ["src", "tests"]                     # Directories or files to scan
 require_param_types = true                   # Require parameter types in docstrings
 check_references = true                      # Check references for proper format
+check_type_consistency = true                # Compare docstring types with annotations
 exclude_files = ["conftest.py", "__init__.py"] # Files to exclude from checks
+min_short_description_length = 50            # Minimum short description length; 0 to disable
+max_short_description_length = 160           # Maximum short description length; 0 to disable (SEO: 120-160)
 verbose = false                              # Enable verbose output
 ```

{google_docstring_parser-0.0.9 → google_docstring_parser-0.0.11}/README.md

@@ -119,6 +119,10 @@ References:
 
 Each reference is parsed into a dictionary with `description` and `source` keys. URLs in the source are properly handled, ensuring colons in URLs are not confused with the separator colon.
 
+## Short Description (Meta Description)
+
+The checker extracts the **short description** as the first paragraph (up to the first blank line). Multi-line first paragraphs are joined with spaces. This is useful for meta descriptions on documentation sites. SEO best practice: 120-160 characters. Use `min_short_description_length` and `max_short_description_length` to enforce bounds (0 to disable).
+
 ## Pre-commit Hook
 
 This package includes a pre-commit hook that checks if Google-style docstrings in your codebase can be parsed correctly.
@@ -146,6 +150,9 @@ Add a `[tool.docstring_checker]` section to your pyproject.toml:
 paths = ["src", "tests"]                     # Directories or files to scan
 require_param_types = true                   # Require parameter types in docstrings
 check_references = true                      # Check references for proper format
+check_type_consistency = true                # Compare docstring types with annotations
 exclude_files = ["conftest.py", "__init__.py"] # Files to exclude from checks
+min_short_description_length = 50            # Minimum short description length; 0 to disable
+max_short_description_length = 160           # Maximum short description length; 0 to disable (SEO: 120-160)
 verbose = false                              # Enable verbose output
 ```

{google_docstring_parser-0.0.9 → google_docstring_parser-0.0.11}/google_docstring_parser/google_docstring_parser.py

@@ -40,7 +40,7 @@ __all__ = [
 
 
 class ReferenceFormatError(ValueError):
-    """Error raised when a reference format is invalid.
+    """Error raised when a reference format is invalid or malformed.
 
     Args:
         code (str): Error code identifying the specific format issue
@@ -88,7 +88,7 @@ class EmptyDescriptionError(ReferenceFormatError):
 
 
 def _extract_sections(docstring: str) -> dict[str, str]:
-    """Extract sections from a docstring.
+    """Extract named sections from a Google-style docstring.
 
     Args:
         docstring (str): The docstring to extract sections from
@@ -170,7 +170,7 @@ def _find_separator_colon(content: str) -> int:
 
 
 def _parse_reference_line(line: str, *, is_single: bool = False) -> dict[str, str]:
-    """Parse a single reference line.
+    """Parse a single reference line into description and source.
 
     Args:
         line (str): The line to parse
@@ -252,7 +252,7 @@ def _identify_main_reference_lines(lines: list[str]) -> list[str]:
 
 
 def _process_single_reference(main_line: str, all_lines: list[str]) -> dict[str, str]:
-    """Process a single reference entry.
+    """Process a single reference entry from the References section.
 
     Args:
         main_line (str): The main reference line
@@ -285,7 +285,7 @@ def _process_single_reference(main_line: str, all_lines: list[str]) -> dict[str,
 
 
 def _process_multiple_references(lines: list[str]) -> list[dict[str, str]]:
-    """Process multiple reference entries.
+    """Process multiple reference entries from the References section.
 
     Args:
         lines (list[str]): Lines containing multiple references
@@ -338,7 +338,7 @@ def _process_multiple_references(lines: list[str]) -> list[dict[str, str]]:
 
 
 def _parse_references(reference_content: str) -> list[dict[str, str]]:
-    """Parse references section content.
+    """Parse references section content into structured reference entries.
 
     Args:
         reference_content (str): Content of the references section
@@ -373,7 +373,7 @@ def _parse_references(reference_content: str) -> list[dict[str, str]]:
 
 
 def _validate_type_with_error_handling(type_str: str, result: dict[str, Any], collect_errors: bool) -> None:
-    """Validate a type annotation and handle any errors.
+    """Validate a type annotation and handle any validation errors.
 
     This function validates type annotations and handles errors differently based on the collect_errors flag:
     - When collect_errors is True: Errors are added to result["errors"] list instead of being raised
@@ -408,7 +408,7 @@ def _process_args_with_validation(
     validate_types: bool,
     collect_errors: bool,
 ) -> None:
-    """Process the Args section with type validation.
+    """Process the Args section with type validation and error collection.
 
     Args:
         sections (dict[str, str]): The sections dictionary
@@ -439,7 +439,7 @@ def _process_args_with_validation(
 
 
 def _parse_returns_section(sections: dict[str, str], *, validate_types: bool) -> dict[str, str] | str:
-    """Process the Returns section of a docstring.
+    """Process the Returns section of a docstring into type and description.
 
     Args:
         sections (dict[str, str]): The sections dictionary
@@ -482,7 +482,7 @@ def _process_returns_with_validation(
     validate_types: bool,
     collect_errors: bool,
 ) -> None:
-    """Process the Returns section with type validation.
+    """Process the Returns section with type validation and error handling.
 
     Args:
         sections (dict[str, str]): The sections dictionary
@@ -506,7 +506,7 @@ def _process_returns_with_validation(
 
 
 def _process_references_section(sections: dict[str, str], result: dict[str, Any]) -> None:
-    """Process the References section.
+    """Process the References section into structured reference entries.
 
     Args:
         sections (dict[str, str]): The sections dictionary
@@ -527,7 +527,7 @@ def parse_google_docstring(
     validate_types: bool = True,
     collect_errors: bool = True,
 ) -> dict[str, Any]:
-    """Parse a Google-style docstring.
+    """Parse a Google-style docstring into a structured dictionary.
 
     Args:
         docstring (str): The docstring to parse

{google_docstring_parser-0.0.9 → google_docstring_parser-0.0.11}/google_docstring_parser/type_validation.py

@@ -89,7 +89,7 @@ NESTING_KEYWORD = "with"
 
 
 class InvalidTypeAnnotationError(ValueError):
-    """Error raised when a type annotation is invalid.
+    """Error raised when a type annotation is invalid or malformed.
 
     Args:
         message (str): The error message.
@@ -100,7 +100,7 @@ class InvalidTypeAnnotationError(ValueError):
     INVALID_NESTED_TYPE = "Invalid nested type: {}"
 
     def __init__(self, message: str) -> None:
-        """Initialize the error with a message.
+        """Initialize the error instance with a descriptive message.
 
         Args:
             message (str): The error message.
@@ -125,7 +125,7 @@ class BracketValidationError(ValueError):
     WRONG_BRACKET_TYPE = "Collection '{}' must use square brackets for type arguments, not '{}'"
 
     def __init__(self, error_type: str) -> None:
-        """Initialize with a specific error type.
+        """Initialize the error with a specific bracket validation type.
 
         Args:
             error_type (str): One of the predefined error types.
@@ -137,7 +137,7 @@ class BracketValidationError(ValueError):
 
 
 def is_collection_type(type_name: str) -> bool:
-    """Check if a type name is a known collection type.
+    """Check if a type name is a known collection type (list, dict, etc).
 
     Args:
         type_name (str): The type name to check.
@@ -261,7 +261,7 @@ def _is_within_string_literal(text: str, position: int) -> bool:
 
 
 def _looks_like_type_annotation(text: str) -> bool:
-    """Check if text looks like a type annotation.
+    """Check if text looks like a type annotation using heuristics.
 
     Args:
         text (str): The text to check
@@ -277,7 +277,7 @@ def _looks_like_type_annotation(text: str) -> bool:
 
 
 def _process_string_literals(text: str) -> tuple[str, list[str]]:
-    """Process string literals in text.
+    """Process string literals in text by replacing them with placeholders.
 
     Args:
         text (str): The text to process
@@ -386,7 +386,7 @@ def _check_for_opening_bracket(
     bracket_stack: list[str],
     collection_stack: list[tuple[str, str]],
 ) -> None:
-    """Check for opening bracket in type declaration.
+    """Check for opening bracket in type declaration and update stacks.
 
     Args:
         tokens (list[str]): List of tokens
@@ -409,7 +409,7 @@ def _check_for_opening_bracket(
 
 
 def _check_for_closing_bracket(token: str, bracket_stack: list[str], collection_stack: list[tuple[str, str]]) -> None:
-    """Check for closing bracket in type declaration.
+    """Check for closing bracket in type declaration and validate pairing.
 
     Args:
         token (str): Current token
@@ -440,7 +440,7 @@ def _check_for_closing_bracket(token: str, bracket_stack: list[str], collection_
 
 
 def _check_for_bare_collection(tokens: list[str], i: int, token: str) -> None:
-    """Check for bare collection type usage.
+    """Check for bare collection type usage without type arguments.
 
     Args:
         tokens (list[str]): List of tokens
@@ -487,7 +487,7 @@ def _is_bare_collection_in_nested_type(token: str, tokens: list[str], i: int, br
 
 
 def _check_tokens_for_collection_type_usage(tokens: list[str]) -> None:
-    """Check tokens for proper collection type usage.
+    """Check tokens for proper collection type usage and brackets.
 
     Args:
         tokens (list[str]): List of tokens to check
@@ -539,7 +539,7 @@ def _check_tokens_for_collection_type_usage(tokens: list[str]) -> None:
 
 
 def _validate_type_declaration(declaration: str) -> None:
-    """Validate a type declaration.
+    """Validate a type declaration for syntax and collection usage.
 
     Args:
         declaration (str): The type declaration to validate

{google_docstring_parser-0.0.9 → google_docstring_parser-0.0.11}/google_docstring_parser.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-docstring-parser
-Version: 0.0.9
+Version: 0.0.11
 Summary: A lightweight, efficient parser for Google-style Python docstrings that converts them into structured dictionaries.
 Author: Vladimir Iglovikov
 Maintainer: Vladimir Iglovikov
@@ -153,6 +153,10 @@ References:
 
 Each reference is parsed into a dictionary with `description` and `source` keys. URLs in the source are properly handled, ensuring colons in URLs are not confused with the separator colon.
 
+## Short Description (Meta Description)
+
+The checker extracts the **short description** as the first paragraph (up to the first blank line). Multi-line first paragraphs are joined with spaces. This is useful for meta descriptions on documentation sites. SEO best practice: 120-160 characters. Use `min_short_description_length` and `max_short_description_length` to enforce bounds (0 to disable).
+
 ## Pre-commit Hook
 
 This package includes a pre-commit hook that checks if Google-style docstrings in your codebase can be parsed correctly.
@@ -180,6 +184,9 @@ Add a `[tool.docstring_checker]` section to your pyproject.toml:
 paths = ["src", "tests"]                     # Directories or files to scan
 require_param_types = true                   # Require parameter types in docstrings
 check_references = true                      # Check references for proper format
+check_type_consistency = true                # Compare docstring types with annotations
 exclude_files = ["conftest.py", "__init__.py"] # Files to exclude from checks
+min_short_description_length = 50            # Minimum short description length; 0 to disable
+max_short_description_length = 160           # Maximum short description length; 0 to disable (SEO: 120-160)
 verbose = false                              # Enable verbose output
 ```

{google_docstring_parser-0.0.9 → google_docstring_parser-0.0.11}/pyproject.toml

@@ -5,7 +5,7 @@ requires = [ "setuptools>=45", "wheel" ]
 
 [project]
 name = "google-docstring-parser"
-version = "0.0.9"
+version = "0.0.11"
 
 description = "A lightweight, efficient parser for Google-style Python docstrings that converts them into structured dictionaries."
 readme = "README.md"
@@ -119,6 +119,7 @@ lint.per-file-ignores = { "__init__.py" = [
   "BLE001",
   "FBT002",
   "ANN201",
+  "PLR0913",
 ] }
 
 lint.fixable = [ "ALL" ]
@@ -146,5 +147,6 @@ paths = [ "google_docstring_parser", "tools" ]
 require_param_types = true
 check_references = true
 check_type_consistency = true
+min_short_description_length = 50
 exclude_files = [ "test_malformed_docstrings.py" ]
 verbose = false

{google_docstring_parser-0.0.9 → google_docstring_parser-0.0.11}/tools/check_docstrings.py

@@ -20,18 +20,24 @@ from google_docstring_parser.google_docstring_parser import (
     parse_google_docstring,
 )
 
+# Preview length for short description error messages
+SHORT_DESC_PREVIEW_LENGTH = 50
+
 # Default configuration
 DEFAULT_CONFIG = {
     "paths": [],  # Empty by default, so no directories are scanned unless explicitly specified
     "require_param_types": False,
     "check_references": True,
+    "check_type_consistency": False,
+    "min_short_description_length": 0,
+    "max_short_description_length": 0,  # 160 recommended for SEO meta descriptions
     "exclude_files": [],
     "verbose": False,
 }
 
 
 class DocstringContext(NamedTuple):
-    """Context for docstring processing.
+    """Context for docstring processing, validation, and error reporting.
 
     Args:
         file_path (Path): Path to the file
@@ -40,6 +46,10 @@ class DocstringContext(NamedTuple):
         verbose (bool): Whether to print verbose output
         require_param_types (bool): Whether parameter types are required
         check_references (bool): Whether to check references for errors
+        check_type_consistency (bool): Whether to compare docstring types with annotations
+        min_short_description_length (int): Minimum length for short description
+        max_short_description_length (int): Maximum length for short description (0 to disable)
+        node (ast.AST | None): AST node for the function or class
 
     Returns:
         DocstringContext: A named tuple containing docstring processing context
@@ -51,6 +61,35 @@ class DocstringContext(NamedTuple):
     verbose: bool
     require_param_types: bool = False
     check_references: bool = True
+    check_type_consistency: bool = False
+    min_short_description_length: int = 0
+    max_short_description_length: int = 0
+    node: ast.AST | None = None
+
+
+_CONFIG_KEYS: dict[str, tuple[str, type]] = {
+    "paths": ("paths", list),
+    "require_param_types": ("require_param_types", bool),
+    "check_references": ("check_references", bool),
+    "check_type_consistency": ("check_type_consistency", bool),
+    "min_short_description_length": ("min_short_description_length", int),
+    "max_short_description_length": ("max_short_description_length", int),
+    "exclude_files": ("exclude_files", list),
+    "verbose": ("verbose", bool),
+}
+
+
+def _config_keys_match() -> bool:
+    """Return True if DEFAULT_CONFIG and _CONFIG_KEYS have the same keys."""
+    return set(DEFAULT_CONFIG.keys()) == set(_CONFIG_KEYS.keys())
+
+
+def _apply_tool_config(config: dict[str, Any], tool_config: dict[str, Any]) -> None:
+    """Apply tool_config values to config. Modifies config in place."""
+    for key, (config_key, converter) in _CONFIG_KEYS.items():
+        if key in tool_config:
+            raw = tool_config[key]
+            config[config_key] = raw if converter is list else converter(raw)
 
 
 def load_pyproject_config() -> dict[str, Any]:
@@ -60,8 +99,6 @@ def load_pyproject_config() -> dict[str, Any]:
         dict[str, Any]: Dictionary with configuration values
     """
     config = DEFAULT_CONFIG.copy()
-
-    # Look for pyproject.toml in the current directory
     pyproject_path = Path("pyproject.toml")
     if not pyproject_path.is_file():
         return config
@@ -69,24 +106,10 @@ def load_pyproject_config() -> dict[str, Any]:
     try:
         with pyproject_path.open("rb") as f:
             pyproject_data = tomli.load(f)
-
-        # Check if our tool is configured
         tool_config = pyproject_data.get("tool", {}).get("docstring_checker", {})
         if not tool_config:
             return config
-
-        # Update config with values from pyproject.toml
-        if "paths" in tool_config:
-            config["paths"] = tool_config["paths"]
-        if "require_param_types" in tool_config:
-            config["require_param_types"] = bool(tool_config["require_param_types"])
-        if "check_references" in tool_config:
-            config["check_references"] = bool(tool_config["check_references"])
-        if "exclude_files" in tool_config:
-            config["exclude_files"] = tool_config["exclude_files"]
-        if "verbose" in tool_config:
-            config["verbose"] = bool(tool_config["verbose"])
-
+        _apply_tool_config(config, tool_config)
     except Exception as e:
         print(f"Warning: Failed to load configuration from pyproject.toml: {e}")
 
@@ -94,7 +117,7 @@ def load_pyproject_config() -> dict[str, Any]:
 
 
 def get_docstrings(file_path: Path) -> list[tuple[str, int, str | None, ast.AST | None]]:
-    """Extract docstrings from a Python file.
+    """Extract docstrings from a Python file using AST parsing.
 
     Args:
         file_path (Path): Path to the Python file
@@ -128,7 +151,7 @@ def get_docstrings(file_path: Path) -> list[tuple[str, int, str | None, ast.AST
 
 
 def check_param_types(docstring_dict: dict[str, Any], require_types: bool) -> list[str]:
-    """Check if all parameters have types if required.
+    """Check if all parameters have types when types are required.
 
     Args:
         docstring_dict (dict[str, Any]): Parsed docstring dictionary
@@ -150,6 +173,111 @@ def check_param_types(docstring_dict: dict[str, Any], require_types: bool) -> li
     return errors
 
 
+def _normalize_type(type_str: str) -> str:
+    """Normalize type string for comparison (quotes and whitespace only).
+
+    Python 3.10+ typing uses list, dict, tuple, X|Y - no List, Dict, Tuple, Union.
+    We do not normalize those; mismatches will be reported.
+    Internal whitespace differences (e.g., around commas, |, or brackets) are ignored.
+
+    Args:
+        type_str (str): Type string to normalize
+
+    Returns:
+        str: Normalized type string
+    """
+    normalized = type_str.strip().strip("'\"")
+    return re.sub(r"\s+", "", normalized)
+
+
+def _annotation_to_str(annotation: ast.expr | None) -> str | None:
+    """Extract the type string from an AST annotation node.
+
+    Args:
+        annotation (ast.expr | None): AST annotation node
+
+    Returns:
+        str | None: Type string or None if no annotation
+    """
+    if annotation is None:
+        return None
+    if isinstance(annotation, ast.Constant) and isinstance(annotation.value, str):
+        return annotation.value
+    return ast.unparse(annotation)
+
+
+def _get_ast_param_types(node: ast.FunctionDef | ast.AsyncFunctionDef) -> dict[str, str]:
+    """Extract parameter names and type strings from function AST.
+
+    Args:
+        node (ast.FunctionDef | ast.AsyncFunctionDef): Function AST node
+
+    Returns:
+        dict[str, str]: Map of param name to annotation string (skips self/cls)
+    """
+    ast_params: dict[str, str] = {}
+    all_args: list[ast.arg] = []
+    all_args.extend(node.args.posonlyargs)
+    all_args.extend(node.args.args)
+    all_args.extend(node.args.kwonlyargs)
+    if node.args.vararg is not None:
+        all_args.append(node.args.vararg)
+    if node.args.kwarg is not None:
+        all_args.append(node.args.kwarg)
+    for arg in all_args:
+        if arg.arg in ("self", "cls"):
+            continue
+        if ann_str := _annotation_to_str(arg.annotation):
+            ast_params[arg.arg] = ann_str
+    return ast_params
+
+
+def check_type_consistency(
+    parsed: dict[str, Any],
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> list[str]:
+    """Compare docstring types with function annotations.
+
+    Args:
+        parsed (dict[str, Any]): Parsed docstring dictionary
+        node (ast.FunctionDef | ast.AsyncFunctionDef): Function AST node
+
+    Returns:
+        list[str]: List of error messages for type mismatches
+    """
+    errors = []
+    ast_params = _get_ast_param_types(node)
+
+    # Compare Args
+    for arg in parsed.get("Args", []):
+        doc_type = arg.get("type")
+        if not doc_type:
+            continue
+        param_name = arg.get("name")
+        if not param_name or param_name not in ast_params:
+            continue
+        ast_type = ast_params[param_name]
+        if _normalize_type(doc_type) != _normalize_type(ast_type):
+            errors.append(
+                f"Parameter '{param_name}': docstring says '{doc_type}' but annotation says '{ast_type}'",
+            )
+
+    # Compare Returns (handle both dict and string "None" from parse_google_docstring)
+    returns = parsed.get("Returns")
+    doc_ret: str | None = None
+    if isinstance(returns, dict):
+        doc_ret = returns.get("type")
+    elif isinstance(returns, str):
+        doc_ret = returns
+    ast_ret = _annotation_to_str(node.returns)
+    if doc_ret and ast_ret and _normalize_type(doc_ret) != _normalize_type(ast_ret):
+        errors.append(
+            f"Returns: docstring says '{doc_ret}' but annotation says '{ast_ret}'",
+        )
+
+    return errors
+
+
 def _check_reference_fields(reference: dict[str, Any], index: int) -> list[str]:
     """Check a single reference for missing or empty fields.
 
@@ -177,7 +305,7 @@ def _check_reference_fields(reference: dict[str, Any], index: int) -> list[str]:
 
 
 def check_references(docstring_dict: dict[str, Any]) -> list[str]:
-    """Check references section for common errors.
+    """Check references section for common formatting errors.
 
     Args:
         docstring_dict (dict[str, Any]): Parsed docstring dictionary
@@ -216,7 +344,7 @@ def check_references(docstring_dict: dict[str, Any]) -> list[str]:
 
 
 def validate_docstring(docstring: str) -> list[str]:
-    """Perform additional validation on a docstring.
+    """Perform additional validation on docstring format and structure.
 
     Args:
         docstring (str): The docstring to validate
@@ -250,7 +378,7 @@ def validate_docstring(docstring: str) -> list[str]:
 
 
 def check_returns_section_name(docstring: str) -> list[str]:
-    """Check for incorrect Returns section names.
+    """Check for incorrect Returns section names (e.g. return vs Returns).
 
     Args:
         docstring (str): The docstring to check
@@ -267,8 +395,73 @@ def check_returns_section_name(docstring: str) -> list[str]:
     return errors
 
 
+def _extract_short_description(description: str) -> str:
+    r"""Extract short description: first paragraph (up to first blank line), normalized.
+
+    Leading and trailing whitespace (including blank lines) are stripped before
+    paragraph detection. Splits on one or more blank lines (\\n\\s*\\n), takes
+    the first part, then normalizes internal whitespace (tabs, newlines, multiple
+    spaces) to single spaces. Joins multi-line first paragraph for meta description use.
+
+    Args:
+        description (str): Full description text
+
+    Returns:
+        str: First paragraph as single line, or empty string
+    """
+    if not description:
+        return ""
+    parts = re.split(r"\n\s*\n", description.strip())
+    first_para = parts[0].strip() if parts else ""
+    return " ".join(first_para.split()) if first_para else ""
+
+
+def check_short_description_length(
+    parsed: dict[str, Any],
+    min_length: int,
+    max_length: int = 0,
+) -> list[str]:
+    """Check that the short description meets length requirements.
+
+    Short description is the first paragraph (up to first blank line).
+    SEO: 120-160 chars recommended for meta descriptions.
+
+    Args:
+        parsed (dict[str, Any]): Parsed docstring dictionary
+        min_length (int): Minimum length (0 to disable)
+        max_length (int): Maximum length (0 to disable)
+
+    Returns:
+        list[str]: List of error messages for length violations
+    """
+    short_desc = _extract_short_description(parsed.get("Description") or "")
+    if not short_desc:
+        return []
+
+    errors: list[str] = []
+    if min_length > 0 and len(short_desc) < min_length:
+        preview = (
+            short_desc[:SHORT_DESC_PREVIEW_LENGTH] + "..."
+            if len(short_desc) > SHORT_DESC_PREVIEW_LENGTH
+            else short_desc
+        )
+        errors.append(
+            f"Short description too short ({len(short_desc)} chars, min {min_length}): '{preview}'",
+        )
+    if max_length > 0 and len(short_desc) > max_length:
+        preview = (
+            short_desc[:SHORT_DESC_PREVIEW_LENGTH] + "..."
+            if len(short_desc) > SHORT_DESC_PREVIEW_LENGTH
+            else short_desc
+        )
+        errors.append(
+            f"Short description too long ({len(short_desc)} chars, max {max_length}): '{preview}'",
+        )
+    return errors
+
+
 def check_returns_type(docstring_dict: dict[str, Any]) -> list[str]:
-    """Check Returns type in a docstring."""
+    """Check that the Returns section has proper type annotation."""
     errors = []
     if returns := docstring_dict.get("Returns"):
         # Special case: Returns section just contains "None"
@@ -286,7 +479,7 @@ def check_returns_type(docstring_dict: dict[str, Any]) -> list[str]:
 
 
 def _format_error(context: DocstringContext, error: str) -> str:
-    """Format an error message consistently.
+    """Format an error message consistently with file, line, and name.
 
     Args:
         context (DocstringContext): Docstring context
@@ -333,7 +526,7 @@ def safe_execute(
 
 
 def _check_returns_section(context: DocstringContext, docstring: str) -> list[str]:
-    """Check the Returns section name.
+    """Check the Returns section name for correct spelling.
 
     Args:
         context (DocstringContext): Docstring context
@@ -352,7 +545,7 @@ def _check_returns_section(context: DocstringContext, docstring: str) -> list[st
 
 
 def _validate_docstring_format(context: DocstringContext, docstring: str) -> list[str]:
-    """Validate docstring format.
+    """Validate docstring format for common structural issues.
 
     Args:
         context (DocstringContext): Docstring context
@@ -371,7 +564,7 @@ def _validate_docstring_format(context: DocstringContext, docstring: str) -> lis
 
 
 def _parse_and_check_returns(context: DocstringContext, docstring: str) -> tuple[list[str], dict[str, Any] | None]:
-    """Parse docstring and check returns type.
+    """Parse docstring and check that the Returns section has proper type.
 
     Args:
         context (DocstringContext): Docstring context
@@ -408,7 +601,7 @@ def _parse_and_check_returns(context: DocstringContext, docstring: str) -> tuple
 
 
 def _check_additional_validations(context: DocstringContext, parsed: dict[str, Any]) -> list[str]:
-    """Run additional validations on parsed docstring.
+    """Run additional validations on the parsed docstring dictionary.
 
     Args:
         context (DocstringContext): Docstring context
@@ -438,11 +631,36 @@ def _check_additional_validations(context: DocstringContext, parsed: dict[str, A
         )
         errors.extend(ref_errors)
 
+    if context.min_short_description_length > 0 or context.max_short_description_length > 0:
+        length_errors, _ = safe_execute(
+            context,
+            check_short_description_length,
+            parsed,
+            context.min_short_description_length,
+            context.max_short_description_length,
+            error_prefix="Error checking short description length",
+        )
+        errors.extend(length_errors)
+
+    if (
+        context.check_type_consistency
+        and context.node is not None
+        and isinstance(context.node, (ast.FunctionDef, ast.AsyncFunctionDef))
+    ):
+        consistency_errors, _ = safe_execute(
+            context,
+            check_type_consistency,
+            parsed,
+            context.node,
+            error_prefix="Error checking type consistency",
+        )
+        errors.extend(consistency_errors)
+
     return errors
 
 
 def _process_docstring(context: DocstringContext, docstring: str) -> list[str]:
-    """Process a single docstring.
+    """Process a single docstring and collect all validation errors.
 
     Args:
         context (DocstringContext): Docstring context
@@ -482,14 +700,20 @@ def check_file(
     require_param_types: bool = False,
     verbose: bool = False,
     check_references: bool = True,
+    check_type_consistency: bool = False,
+    min_short_description_length: int = 0,
+    max_short_description_length: int = 0,
 ) -> list[str]:
-    """Check docstrings in a file.
+    """Check docstrings in a Python file for parsing and validation errors.
 
     Args:
         file_path (Path): Path to the Python file
         require_param_types (bool): Whether parameter types are required
         verbose (bool): Whether to print verbose output
         check_references (bool): Whether to check references for errors
+        check_type_consistency (bool): Whether to compare docstring types with annotations
+        min_short_description_length (int): Minimum length for short description (0 to disable)
+        max_short_description_length (int): Maximum length for short description (0 to disable)
 
     Returns:
         list[str]: List of error messages
@@ -508,7 +732,7 @@ def check_file(
             print(error_msg)
         return errors
 
-    for name, line_no, docstring, _ in docstrings:
+    for name, line_no, docstring, node in docstrings:
         context = DocstringContext(
             file_path=file_path,
             line_no=line_no,
@@ -516,6 +740,10 @@ def check_file(
             verbose=verbose,
             require_param_types=require_param_types,
             check_references=check_references,
+            check_type_consistency=check_type_consistency,
+            min_short_description_length=min_short_description_length,
+            max_short_description_length=max_short_description_length,
+            node=node,
         )
         errors.extend(_process_docstring(context, docstring))
 
@@ -528,6 +756,9 @@ def scan_directory(
     require_param_types: bool = False,
     verbose: bool = False,
     check_references: bool = True,
+    check_type_consistency: bool = False,
+    min_short_description_length: int = 0,
+    max_short_description_length: int = 0,
 ) -> list[str]:
     """Scan a directory for Python files and check their docstrings.
 
@@ -537,6 +768,9 @@ def scan_directory(
         require_param_types (bool): Whether parameter types are required
         verbose (bool): Whether to print verbose output
         check_references (bool): Whether to check references for errors
+        check_type_consistency (bool): Whether to compare docstring types with annotations
+        min_short_description_length (int): Minimum length for short description (0 to disable)
+        max_short_description_length (int): Maximum length for short description (0 to disable)
 
     Returns:
         list[str]: List of error messages
@@ -559,12 +793,22 @@ def scan_directory(
                 break
 
         if not should_exclude:
-            errors.extend(check_file(py_file, require_param_types, verbose, check_references))
+            errors.extend(
+                check_file(
+                    py_file,
+                    require_param_types,
+                    verbose,
+                    check_references,
+                    check_type_consistency,
+                    min_short_description_length,
+                    max_short_description_length,
+                ),
+            )
     return errors
 
 
 def _parse_args() -> argparse.Namespace:
-    """Parse command line arguments.
+    """Parse command line arguments for the docstring checker.
 
     Returns:
         argparse.Namespace: Parsed command line arguments
@@ -582,29 +826,53 @@ def _parse_args() -> argparse.Namespace:
         action="store_true",
         help="Require parameter types in docstrings",
     )
-    parser.add_argument(
+    ref_group = parser.add_mutually_exclusive_group()
+    ref_group.add_argument(
         "--check-references",
         action="store_true",
         help="Check references for errors",
     )
-    parser.add_argument(
+    ref_group.add_argument(
         "--no-check-references",
         action="store_true",
         help="Skip reference checking",
     )
+    type_consistency_group = parser.add_mutually_exclusive_group()
+    type_consistency_group.add_argument(
+        "--check-type-consistency",
+        action="store_true",
+        help="Compare docstring types with function annotations",
+    )
+    type_consistency_group.add_argument(
+        "--no-check-type-consistency",
+        action="store_true",
+        help="Skip type consistency checking",
+    )
     parser.add_argument(
         "--exclude-files",
         help="Comma-separated list of filenames to exclude",
         default="",
     )
     parser.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
+    parser.add_argument(
+        "--min-short-description-length",
+        type=int,
+        metavar="N",
+        help="Minimum length for short description (0 to disable)",
+    )
+    parser.add_argument(
+        "--max-short-description-length",
+        type=int,
+        metavar="N",
+        help="Maximum length for short description (0 to disable, 160 recommended for SEO)",
+    )
     return parser.parse_args()
 
 
 def _get_config_values(
     args: argparse.Namespace,
     config: dict[str, Any],
-) -> tuple[list[str], bool, bool, bool, list[str]]:
+) -> tuple[list[str], bool, bool, bool, bool, int, int, list[str]]:
     """Get configuration values from command line arguments and config file.
 
     Args:
@@ -612,11 +880,14 @@ def _get_config_values(
         config (dict[str, Any]): Configuration dictionary
 
     Returns:
-        tuple[list[str], bool, bool, bool, list[str]]: Tuple containing:
+        tuple[list[str], bool, bool, bool, bool, int, int, list[str]]: Tuple containing:
             - List of paths to check
             - Whether to require parameter types
-            - Whether to check references
             - Whether to enable verbose output
+            - Whether to check references
+            - Whether to check type consistency
+            - Minimum short description length
+            - Maximum short description length
             - List of files to exclude
     """
     # Get paths
@@ -628,13 +899,20 @@ def _get_config_values(
     # Get verbose
     verbose = args.verbose or config["verbose"]
 
-    # Get check_references - handle both positive and negative flags
+    # Get check_references - handle both positive and negative flags (mutually exclusive)
     check_references = config["check_references"]
     if args.check_references:
         check_references = True
     if args.no_check_references:
         check_references = False
 
+    # Get check_type_consistency - handle both positive and negative flags (mutually exclusive)
+    check_type_consistency = config.get("check_type_consistency", False)
+    if args.check_type_consistency:
+        check_type_consistency = True
+    if args.no_check_type_consistency:
+        check_type_consistency = False
+
     # Get exclude_files
     exclude_files = []
     if args.exclude_files:
@@ -644,7 +922,26 @@ def _get_config_values(
     if not exclude_files:
         exclude_files = config["exclude_files"]
 
-    return paths, require_param_types, verbose, check_references, exclude_files
+    # Get min_short_description_length - CLI overrides config
+    min_short_description_length = config.get("min_short_description_length", 0)
+    if args.min_short_description_length is not None:
+        min_short_description_length = args.min_short_description_length
+
+    # Get max_short_description_length - CLI overrides config
+    max_short_description_length = config.get("max_short_description_length", 0)
+    if args.max_short_description_length is not None:
+        max_short_description_length = args.max_short_description_length
+
+    return (
+        paths,
+        require_param_types,
+        verbose,
+        check_references,
+        check_type_consistency,
+        min_short_description_length,
+        max_short_description_length,
+        exclude_files,
+    )
 
 
 def _process_paths(
@@ -653,8 +950,11 @@ def _process_paths(
     require_param_types: bool,
     verbose: bool,
     check_references: bool,
+    check_type_consistency: bool,
+    min_short_description_length: int,
+    max_short_description_length: int,
 ) -> list[str]:
-    """Process paths and check docstrings.
+    """Process paths and check docstrings in each file or directory.
 
     Args:
         paths (list[str]): List of paths to check
@@ -662,6 +962,9 @@ def _process_paths(
         require_param_types (bool): Whether parameter types are required
         verbose (bool): Whether to print verbose output
         check_references (bool): Whether to check references for errors
+        check_type_consistency (bool): Whether to compare docstring types with annotations
+        min_short_description_length (int): Minimum length for short description (0 to disable)
+        max_short_description_length (int): Maximum length for short description (0 to disable)
 
     Returns:
         list[str]: List of error messages
@@ -670,10 +973,27 @@ def _process_paths(
     for path_str in paths:
         path = Path(path_str)
         if path.is_dir():
-            errors = scan_directory(path, exclude_files, require_param_types, verbose, check_references)
+            errors = scan_directory(
+                path,
+                exclude_files,
+                require_param_types,
+                verbose,
+                check_references,
+                check_type_consistency,
+                min_short_description_length,
+                max_short_description_length,
+            )
             all_errors.extend(errors)
         elif path.is_file() and path.suffix == ".py":
-            errors = check_file(path, require_param_types, verbose, check_references)
+            errors = check_file(
+                path,
+                require_param_types,
+                verbose,
+                check_references,
+                check_type_consistency,
+                min_short_description_length,
+                max_short_description_length,
+            )
             all_errors.extend(errors)
         else:
             print(f"Error: {path} is not a directory or Python file")
@@ -681,7 +1001,7 @@ def _process_paths(
 
 
 def main() -> None:
-    """Run the docstring checker.
+    """Run the docstring checker and exit with appropriate status code.
 
     Returns:
         None
@@ -693,7 +1013,16 @@ def main() -> None:
     args = _parse_args()
 
     # Get configuration values
-    paths, require_param_types, verbose, check_references, exclude_files = _get_config_values(args, config)
+    (
+        paths,
+        require_param_types,
+        verbose,
+        check_references,
+        check_type_consistency,
+        min_short_description_length,
+        max_short_description_length,
+        exclude_files,
+    ) = _get_config_values(args, config)
 
     # Print configuration if verbose
     if verbose:
@@ -701,6 +1030,9 @@ def main() -> None:
         print(f"  Paths: {paths}")
         print(f"  Require parameter types: {require_param_types}")
         print(f"  Check references: {check_references}")
+        print(f"  Check type consistency: {check_type_consistency}")
+        print(f"  Min short description length: {min_short_description_length}")
+        print(f"  Max short description length: {max_short_description_length}")
         print(f"  Exclude files: {exclude_files}")
 
     # Check if paths is empty
@@ -717,6 +1049,9 @@ def main() -> None:
         require_param_types,
         verbose,
         check_references,
+        check_type_consistency,
+        min_short_description_length,
+        max_short_description_length,
     ):
         for error in all_errors:
             print(error)