generate-docstrings
Create docstrings for functions and classes. Use when documenting code APIs.
When & Why to Use This Skill
The Generate Docstrings skill is a specialized developer tool designed to automate the creation of comprehensive, standardized code documentation. It analyzes functions and classes to produce high-quality docstrings in industry-standard formats like Google, NumPy, and reStructuredText, ensuring codebases remain maintainable, readable, and ready for automated API documentation generation.
Use Cases
- Documenting Legacy Codebases: Quickly generate descriptive docstrings for existing undocumented functions to improve code maintainability and team understanding.
- Standardizing Documentation Styles: Enforce consistent documentation conventions across large engineering teams by automatically applying Google or NumPy style guides.
- API Reference Creation: Generate detailed API documentation including parameter constraints, return types, and exceptions to facilitate better integration for third-party developers.
- Enhancing Code Readability: Automatically add practical usage examples and clear summaries to complex logic, reducing the learning curve for new contributors.
| name | generate-docstrings |
|---|---|
| description | "Create docstrings for functions and classes. Use when documenting code APIs." |
| mcp_fallback | none |
| category | generation |
| tier | 2 |
| user-invocable | false |
Generate Docstrings
Write comprehensive docstrings for functions and classes following standard formats (Google, NumPy, reStructuredText).
When to Use
- Adding documentation to undocumented functions
- Improving code documentation completeness
- Ensuring consistent docstring format
- Supporting API documentation generation
Quick Reference
# Google-style docstring format
def matrix_multiply(a: ExTensor, b: ExTensor) -> ExTensor:
"""Multiply two matrices using optimized Mojo kernels.
Args:
a: First matrix (shape: m x n)
b: Second matrix (shape: n x k)
Returns:
Product matrix (shape: m x k)
Raises:
ValueError: If matrix dimensions don't align for multiplication
Example:
```mojo
>> a = ExTensor([[1, 2], [3, 4]], DType.float32)
>>> b = ExTensor([[1, 0], [0, 1]], DType.float32)
>>> c = matrix_multiply(a, b)
```
"""
...
Workflow
- Analyze function: Understand purpose, parameters, return value
- Choose format: Select docstring style (Google is recommended)
- Write summary: Clear one-line description
- Document parameters: Type, description, constraints
- Document return: Type and description of return value
- Add examples: Practical usage examples
Output Format
Docstring structure:
- One-line summary
- Extended description (if needed)
- Args section (parameter documentation)
- Returns section (return value documentation)
- Raises section (exceptions)
- Examples section (usage examples)
References
- See
generate-api-docsskill for API documentation generation - See Google Python Style Guide for docstring conventions
- See PEP 257 for Python docstring conventions