fix(docs): enforce Google docstring style for Returns/Raises sections

- Enhanced check_google_docstring_inline_descriptions.py to validate Returns, Raises, and Yields sections

- Updated pre-commit-config.yaml to apply validator to all optimizer files

- Updated copilot-instructions.md with official Google Python Style Guide references

- Updated docs-completion.prompt.md with critical formatting requirements

- Enhanced scripts/README.md with comprehensive validator documentation

- Fixes #110: Prevents line breaks in parameter descriptions across all docstring sections

- Discovered in PR #109: All multi-objective optimizers have Returns section formatting issues

Author: Anselmoo

.github/copilot-instructions.md

@@ -196,12 +196,26 @@ uv run python -c "from opt.abstract_optimizer import AbstractOptimizer; from opt
 - Pre-commit hooks are configured but run `ruff` manually to be sure
 
 ### Docstring Formatting Guidelines (CRITICAL)
-**All optimizer docstrings must follow these strict formatting rules to pass Ruff linting:**
+**All optimizer docstrings must follow [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods) and pass Ruff linting:**
 
+- **Follow Google docstring conventions**:
+  - See [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
+  - See [PEP 257 - Docstring Conventions](https://peps.python.org/pep-0257/)
+  - See [Sphinx Napoleon - Google Style](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)
 - **Accurate indentation**: Use consistent 4-space indentation for all docstring content
-- **No line breaks in Args/Attributes**: Keep parameter descriptions on single lines
+- **CRITICAL - No line breaks in Args/Attributes**: Parameter descriptions MUST start on same line as parameter name
   - ✅ Correct: `n_bats (int): Number of bats in the population. Recommended: 10-50 bats.`
-  - ❌ Wrong: Multi-line parameter descriptions that break across lines
+  - ❌ Wrong: Parameter name on one line, description on next line (common in agent mode)
+  - ❌ Wrong Example:
+    ```python
+    func (Callable[[ndarray], float]):
+        Objective function to minimize. Must accept numpy array.
+    ```
+  - ✅ Correct Example:
+    ```python
+    func (Callable[[ndarray], float]): Objective function to minimize. Must accept numpy array.
+    ```
+  - If description is too long, continue on next line with proper indentation (aligned with first line of description)
 - **Use LaTeX for mathematical symbols** (Ruff RUF002 compliance):
   - ❌ NEVER use unicode: `×` (multiplication sign), `α` (alpha), `β` (beta), etc.
   - ✅ ALWAYS use LaTeX: `$\times$`, `$\alpha$`, `$\beta$`
@@ -212,7 +226,7 @@ uv run python -c "from opt.abstract_optimizer import AbstractOptimizer; from opt
   - Complexity: `O(n $\times$ m)` NOT `O(n × m)`
   - Greek letters: `$\alpha$`, `$\beta$`, `$\gamma$` NOT `α`, `β`, `γ`
   - Budget expressions: `dim $\times$ 10000` NOT `dim×10000`
-- **Pre-commit validation**: Run `pre-commit run -a` before committing to catch RUF002 errors
+- **Pre-commit validation**: Run `pre-commit run -a` before committing to catch RUF002 and formatting errors
 
 ### Creating New Optimizers
 - Inherit from `AbstractOptimizer` class in `opt/abstract_optimizer.py`

.github/prompts/docs-completion.prompt.md

@@ -28,6 +28,45 @@ Stack: VitePress v1.6.4, Vue 3, ECharts, Python 3.10+
 - Modify optimizer algorithm logic
 - Restructure existing 117 algorithm pages
 
+## Docstring Formatting Requirements (CRITICAL)
+
+**All docstrings must follow [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods).**
+
+### Parameter Description Format
+
+**CRITICAL**: Parameter descriptions MUST start on the **same line** as the parameter name. This is the official Google style.
+
+**❌ WRONG** (line break after parameter name - common in agent mode):
+```python
+func (Callable[[ndarray], float]):
+    Objective function to minimize. Must accept numpy array and return scalar.
+    BBOB functions available in `opt.benchmark.functions`.
+```
+
+**✅ CORRECT** (description on same line):
+```python
+func (Callable[[ndarray], float]): Objective function to minimize. Must accept numpy array and return scalar. BBOB functions available in `opt.benchmark.functions`.
+```
+
+**✅ CORRECT** (multi-line with proper indentation):
+```python
+parameter2 (str): This is a longer definition. I need to include so much
+    information that it needs a second line. Notice the indentation.
+```
+
+### Key Rules
+
+1. **No line breaks between parameter name and description**
+2. **Consistent 4-space indentation**
+3. **LaTeX for mathematical symbols**: `$\times$` not `×`, `$\alpha$` not `α`
+4. **Run validation**: `pre-commit run -a` before committing
+
+### References
+
+- [Google Python Style Guide - Functions and Methods](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods)
+- [PEP 257 - Docstring Conventions](https://peps.python.org/pep-0257/)
+- [Sphinx Napoleon - Google Style](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)
+
 ---
 
 ## Workflow

.pre-commit-config.yaml

@@ -35,7 +35,8 @@ repos:
         entry: python scripts/check_google_docstring_inline_descriptions.py
         language: system
         pass_filenames: true
-        files: ^opt/(abstract_optimizer\.py|multi_objective/abstract_multi_objective\.py)$
+        files: ^opt/(abstract_optimizer\.py|multi_objective/abstract_multi_objective\.py|(classical|constrained|evolutionary|gradient_based|metaheuristic|multi_objective|physics_inspired|probabilistic|social_inspired|swarm_intelligence)/.*\.py)$
+        exclude: ^opt/(benchmark|test|__pycache__|visualization)/.*
       # Custom optimizer validator
       - id: validate-optimizer-docs
         name: Validate optimizer COCO/BBOB compliance

scripts/README.md

@@ -1,8 +1,12 @@
-# Batch Docstring Update Script
+# Scripts Documentation
 
-## Overview
+This directory contains validation and generation scripts for the useful-optimizer library.
 
-The `batch_update_docstrings.py` script automates the generation of COCO/BBOB-compliant docstring templates for all optimizer classes in the useful-optimizer library. This eliminates the error-prone and time-consuming manual process of updating 117+ optimizer docstrings.
+## Available Scripts
+
+### 1. `batch_update_docstrings.py` - Docstring Template Generator
+
+Automates the generation of COCO/BBOB-compliant docstring templates for all optimizer classes.
 
 ## Features
 
@@ -96,7 +100,10 @@ uv run python scripts/batch_update_docstrings.py --help
 
 ```
 scripts/
-  └── batch_update_docstrings.py    # Main script
+  ├── batch_update_docstrings.py                    # Main docstring template generator
+  ├── check_google_docstring_inline_descriptions.py # Enforce Google-style inline parameter descriptions
+  ├── validate_optimizer_docs.py                    # Validate COCO/BBOB compliance
+  └── generate_docs.py                              # VitePress documentation generator
 opt/
   ├── classical/                     # 9 optimizers
   ├── constrained/                   # 5 optimizers
@@ -213,6 +220,101 @@ When modifying the script:
 ## Related Documentation
 
 - [COCO/BBOB Template](../.github/prompts/optimizer-docs-template.prompt.md): Complete docstring template guide
+- [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods): Official docstring formatting guidelines
+- [Copilot Instructions](../.github/copilot-instructions.md): Comprehensive project development guidelines
+
+---
+
+## 2. `check_google_docstring_inline_descriptions.py` - Google Style Validator
+
+Enforces Google-style docstring formatting by ensuring parameter descriptions start on the same line as the parameter name.
+
+### Purpose
+
+This script prevents the common mistake of adding line breaks between parameter names and their descriptions, which violates the official Google Python Style Guide.
+
+### What It Checks
+
+**✅ CORRECT** (parameter description on same line):
+```python
+Args:
+    func (Callable[[ndarray], float]): Objective function to minimize.
+    lower_bound (float): Lower bound of search space.
+```
+
+**❌ WRONG** (line break after parameter name):
+```python
+Args:
+    func (Callable[[ndarray], float]):
+        Objective function to minimize.
+    lower_bound (float):
+        Lower bound of search space.
+```
+
+### Usage
+
+The script is automatically run by pre-commit hooks on all optimizer files:
+
+```bash
+# Run manually on specific files
+python scripts/check_google_docstring_inline_descriptions.py opt/swarm_intelligence/particle_swarm.py
+
+# Run via pre-commit (recommended)
+pre-commit run google-docstring-inline-summaries --all-files
+```
+
+### Pre-Commit Integration
+
+Configured in `.pre-commit-config.yaml` to run on:
+- `opt/abstract_optimizer.py`
+- `opt/multi_objective/abstract_multi_objective.py`
+- All optimizer files in: `classical/`, `constrained/`, `evolutionary/`, `gradient_based/`, `metaheuristic/`, `multi_objective/`, `physics_inspired/`, `probabilistic/`, `social_inspired/`, `swarm_intelligence/`
+
+Excludes: `benchmark/`, `test/`, `__pycache__/`, `visualization/`
+
+### Error Messages
+
+```
+opt/swarm_intelligence/particle_swarm.py:45: Docstring entry missing inline summary after type: func (Callable[[ndarray], float]):
+```
+
+### How to Fix
+
+Move the description to the same line as the parameter:
+
+```python
+# Before (WRONG)
+    func (Callable[[ndarray], float]):
+        Objective function to minimize.
+
+# After (CORRECT)
+    func (Callable[[ndarray], float]): Objective function to minimize.
+```
+
+For long descriptions, continue on the next line with proper indentation:
+
+```python
+    parameter2 (str): This is a longer definition. I need to include so much
+        information that it needs a second line. Notice the indentation.
+```
+
+### References
+
+- **Google Python Style Guide**: https://google.github.io/styleguide/pyguide.html#383-functions-and-methods
+- **PEP 257**: https://peps.python.org/pep-0257/
+- **Sphinx Napoleon**: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
+
+---
+
+## 3. `validate_optimizer_docs.py` - COCO/BBOB Compliance Validator
+
+Validates optimizer docstrings for COCO/BBOB scientific benchmarking compliance (see issue [#110](https://github.com/Anselmoo/useful-optimizer/issues/110)).
+
+---
+
+## 4. `generate_docs.py` - VitePress Documentation Generator
+
+Generates VitePress documentation pages from optimizer source code.
 - [COCO Platform](https://coco-platform.org/): Official COCO/BBOB documentation
 - [BBOB Test Suite](https://coco-platform.org/testsuites/bbob/overview.html): Benchmark suite overview
 

scripts/check_google_docstring_inline_descriptions.py

@@ -1,8 +1,8 @@
 """Check Google-style docstring entries have inline summaries.
 
 This enforces a small style rule used in the abstract base classes:
-Within "Args:" and "Attributes:" sections, the item line should contain the
-short description on the same line as the type.
+Within "Args:", "Attributes:", "Returns:", and "Raises:" sections, the item line
+should contain the short description on the same line as the type.
 
 Example (required):
     history (dict[str, list]): Dictionary containing optimization history.
@@ -11,6 +11,15 @@
     history (dict[str, list]):
         Dictionary containing optimization history.
 
+Example (Returns/Raises - required):
+    Returns:
+        float: The computed value.
+
+Example (Returns/Raises - rejected):
+    Returns:
+        float:
+            The computed value.
+
 This script is intentionally scoped via pre-commit to only a small set of files
 to avoid mass changes across the repository.
 """
@@ -23,7 +32,14 @@
 from pathlib import Path
 
 
-_SECTION_HEADERS = {"args:", "arguments:", "attributes:"}
+_SECTION_HEADERS = {
+    "args:",
+    "arguments:",
+    "attributes:",
+    "returns:",
+    "raises:",
+    "yields:",
+}
 
 _NEXT_SECTION_HEADER_RE = re.compile(
     r"^\s{4,}[A-Z][A-Za-z0-9_\- ]*:\s*$"  # e.g. "Returns:", "Notes:", "Methods:"
@@ -39,49 +55,78 @@
 # (no inline summary) -> error
 _ITEM_MISSING_INLINE_SUMMARY_RE = re.compile(r"^\s{8,}[A-Za-z_]\w*\s*\([^)]*\):\s*$")
 
+# For Returns/Raises sections - Match lines like:
+#     type:
+#         Description...  (WRONG - should be on same line)
+# More indented entries (12+ spaces) indicate type declarations
+_RETURNS_TYPE_MISSING_INLINE_RE = re.compile(r"^\s{12,}[\w\[\],\s|]+:\s*$")
+
+# For Returns/Raises sections - Match lines like:
+#     type: Description... (CORRECT)
+_RETURNS_TYPE_WITH_INLINE_RE = re.compile(r"^\s{12,}[\w\[\],\s|]+:\s*\S")
+
 
 def _check_file(path: Path) -> list[str]:
     errors: list[str] = []
     lines = path.read_text(encoding="utf-8").splitlines()
 
     in_target_section = False
+    current_section = None
 
     for idx, line in enumerate(lines, start=1):
         stripped = line.strip().lower()
 
         if stripped in _SECTION_HEADERS:
             in_target_section = True
+            current_section = stripped.rstrip(":")
             continue
 
         if in_target_section:
             # End the section when we hit a blank line or a new section header.
             if stripped == "" or _NEXT_SECTION_HEADER_RE.match(line):
                 in_target_section = False
+                current_section = None
                 continue
 
             # Ignore bullet lists inside sections.
             if line.lstrip().startswith("-"):
                 continue
 
-            if _ITEM_MISSING_INLINE_SUMMARY_RE.match(line):
-                errors.append(
-                    f"{path}:{idx}: Docstring entry missing inline summary after type: {line.strip()}"
-                )
-                continue
-
-            # If it looks like an item, ensure it has an inline summary.
-            if (
-                "(" in line
-                and ")" in line
-                and ":" in line
-                and line.startswith(" " * 8)
-                and not _ITEM_WITH_INLINE_SUMMARY_RE.match(line)
-            ):
-                name_type_prefix = re.match(r"^\s{8,}[A-Za-z_]\w*\s*\([^)]*\):", line)
-                if name_type_prefix and line.strip().endswith(":"):
+            # For Args/Attributes sections (parameter-style)
+            if current_section in ("args", "arguments", "attributes"):
+                if _ITEM_MISSING_INLINE_SUMMARY_RE.match(line):
                     errors.append(
                         f"{path}:{idx}: Docstring entry missing inline summary after type: {line.strip()}"
                     )
+                    continue
+
+                # If it looks like an item, ensure it has an inline summary.
+                if (
+                    "(" in line
+                    and ")" in line
+                    and ":" in line
+                    and line.startswith(" " * 8)
+                    and not _ITEM_WITH_INLINE_SUMMARY_RE.match(line)
+                ):
+                    name_type_prefix = re.match(
+                        r"^\s{8,}[A-Za-z_]\w*\s*\([^)]*\):", line
+                    )
+                    if name_type_prefix and line.strip().endswith(":"):
+                        errors.append(
+                            f"{path}:{idx}: Docstring entry missing inline summary after type: {line.strip()}"
+                        )
+
+            # For Returns/Raises/Yields sections (type-style)
+            elif current_section in ("returns", "raises", "yields"):
+                # Check for type declarations missing inline summaries
+                # Lines with just "type:" and nothing after should have description on same line
+                # Avoid false positives on continuation lines (those starting with -)
+                if _RETURNS_TYPE_MISSING_INLINE_RE.match(
+                    line
+                ) and not line.lstrip().startswith("-"):
+                    errors.append(
+                        f"{path}:{idx}: {current_section.capitalize()} entry missing inline summary after type: {line.strip()}"
+                    )
 
     return errors