Claude-skill-registry docstring-generator

Generate language-specific docstrings for C#, Java, Python, and TypeScript following industry standards (PEP 257, Javadoc, JSDoc, XML documentation)

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/docstring-generator" ~/.claude/skills/majiayu000-claude-skill-registry-docstring-generator && rm -rf "$T"

manifest: skills/data/docstring-generator/SKILL.md

What I do

I generate language-specific docstrings and documentation following industry standards:

Detect Language: Analyze file extension and project structure to determine language
Detect Docstring Style: Identify existing docstring conventions in codebase
Generate Docstrings: Create appropriate docstrings following language conventions
Support Multiple Formats:
- Python: PEP 257 (Google, NumPy, Sphinx/reST styles)
- Java: Javadoc format with @param, @return, @throws
- TypeScript: JSDoc/TSDoc format with @param, @returns, @throws
- C#: XML documentation comments with <summary>, <param>, <returns>, <exception>
Handle Various Types: Functions, methods, classes, interfaces, properties, exceptions
Enforce Documentation: Ensure docstrings are added during PR workflow

When to use me

Use this workflow when:

Implementing new functions, classes, or methods in Python, Java, TypeScript, or C#
Refactoring code and updating documentation
Creating new APIs or public interfaces
Following documentation best practices and industry standards
Need to ensure all public code has proper docstrings
Preparing code for code review and maintainability

Integration: This skill integrates with

pr-creation-workflow

and

linting-workflow

to enforce docstring presence as part of quality checks.

Prerequisites

Source code files (.py, .java, .ts, .tsx, .cs, .csx)
File permissions to read and write files
Knowledge of preferred docstring style (optional, can auto-detect)
For workflow integration: Git repository initialized

Supported Languages and Standards

Python

Standard: PEP 257 compliant Supported Styles:

Google Style (recommended for most projects)
NumPy Style (for scientific computing)
Sphinx/reST Style (for documentation generation)

Features:

Type hints support (Python 3.5+)
Exception documentation with Raises section
Parameter documentation with Args section
Return value documentation with Returns section
Example code blocks in docstrings

Java

Standard: Javadoc Supported Tags:

```
@param
```
- Parameter documentation
```
@return
```
/
```
@returns
```
- Return value documentation
```
@throws
```
- Exception documentation
```
@see
```
- Related references
```
@author
```
- Author information
```
@version
```
- Version information
```
@since
```
- Since version
```
@deprecated
```
- Deprecation notice
```
@link
```
- Link to related code

Features:

Generic type parameters
Method overload documentation
Interface documentation
Annotation documentation
Inheritance documentation

TypeScript

Standard: JSDoc / TSDoc Supported Tags:

```
@param
```
- Parameter documentation
```
@returns
```
/
```
@return
```
- Return value documentation
```
@throws
```
- Exception documentation
```
@type
```
- Type definitions
```
@example
```
- Usage examples
```
@see
```
- Related references
```
@deprecated
```
- Deprecation notice
```
@interface
```
- Interface documentation
```
@extends
```
- Inheritance documentation

Features:

Generic type parameters
Union types documentation
Optional parameters
Interface and class documentation
Module documentation

C#

Standard: XML Documentation Comments Supported Tags:

```
<summary>
```
- Brief description
```
<param name="">
```
- Parameter documentation
```
<returns>
```
- Return value documentation
```
<exception cref="">
```
- Exception documentation
```
<typeparam>
```
- Generic type parameter documentation
```
<remarks>
```
- Additional remarks
```
<example>
```
- Code examples
```
<seealso>
```
- Related references

Features:

Generic type parameters
Method overload documentation
Property documentation
Event handler documentation
XML attribute escaping

Steps

Step 1: Detect Language

Analyze file to determine programming language:

# Check file extension
case "$file_ext" in
    py)    LANG="python" ;;
    java)   LANG="java" ;;
    ts|tsx) LANG="typescript" ;;
    cs|csx) LANG="csharp" ;;
    *)      LANG="unknown" ;;
esac

echo "Detected language: $LANG"

Step 2: Detect Docstring Style

Analyze existing docstrings in codebase to maintain consistency:

# Python style detection
if grep -q '"""' file.py; then
    if grep -q 'Args:' file.py; then
        STYLE="google"
    elif grep -q 'Parameters' file.py; then
        STYLE="numpy"
    elif grep -q ':param' file.py; then
        STYLE="sphinx"
    fi
fi

echo "Detected docstring style: $STYLE"

Step 3: Analyze Function/Method

Extract function signature and determine docstring needs:

# Extract function/method signature
if [[ "$LANG" == "python" ]]; then
    # Python function
    FUNCTION=$(grep -A 5 'def ' file.py | head -1)
elif [[ "$LANG" == "java" ]]; then
    # Java method
    METHOD=$(grep -B 2 'public.*(' file.java | head -1)
fi

echo "Function to document: $FUNCTION"

Step 4: Generate Docstring

Generate appropriate docstring based on language and style:

Python (Google Style)

def calculate_sum(a: int, b: int) -> int:
    """Calculate the sum of two integers.

    Args:
        a: The first integer to add.
        b: The second integer to add.

    Returns:
        The sum of a and b.

    Raises:
        TypeError: If either a or b is not an integer.

    Examples:
        >>> calculate_sum(5, 3)
        8
    """
    return a + b

Java (Javadoc)

/**
 * Calculates the sum of two integers.
 *
 * @param a The first integer to add
 * @param b The second integer to add
 * @return The sum of a and b
 * @throws IllegalArgumentException If either a or b is not an integer
 *
 * @see #calculateProduct(int, int)
 * @since 1.0
 * @author Developer Name
 */
public int calculateSum(int a, int b) {
    return a + b;
}

TypeScript (JSDoc)

/**
 * Calculates the sum of two integers.
 *
 * @param a - The first integer to add
 * @param b - The second integer to add
 * @returns The sum of a and b
 * @throws {TypeError} If either a or b is not an integer
 *
 * @example
 * ```typescript
 * const result = calculateSum(5, 3); // returns 8
 * ```
 *
 * @see calculateProduct
 * @since 1.0.0
 */
function calculateSum(a: number, b: number): number {
    return a + b;
}

C# (XML Documentation)

/// <summary>
/// Calculates the sum of two integers.
/// </summary>
/// <param name="a">The first integer to add</param>
/// <param name="b">The second integer to add</param>
/// <returns>The sum of a and b</returns>
/// <exception cref="System.ArgumentException">
/// Thrown when either a or b is not an integer
/// </exception>
/// <example>
/// <code>
/// int result = CalculateSum(5, 3); // returns 8
/// </code>
/// </example>
/// <seealso cref="CalculateProduct"/>
public int CalculateSum(int a, int b) {
    return a + b;
}

Step 5: Update File

Insert docstring into the correct location in the file:

# Find function/method start line
LINE_NUM=$(grep -n "^def\|^public.*(" "$FILE" | head -1 | cut -d: -f1)

# Insert docstring after signature (line + 1)
sed -i "$((LINE_NUM+1))i\\$DOCSTRING" "$FILE"

Docstring Format Reference

Python Styles

Google Style (Recommended)

def function_name(param1: type, param2: type) -> return_type:
    """
    Brief one-line description.

    Longer description of function's purpose and behavior.

    Args:
        param1: Description of param1 with its type.
        param2: Description of param2 with its type.

    Returns:
        Description of return value and its type.

    Raises:
        ErrorType: Condition when error is raised.

    Examples:
        >>> function_name(arg1, arg2)
        Expected output
    """

NumPy Style

def function_name(param1, param2):
    """
    Brief description.

    Extended description.

    Parameters
    ----------
    param1 : type
        Description of param1.
    param2 : type
        Description of param2.

    Returns
    -------
    return_type
        Description of return value.

    Raises
    ------
    ErrorType
        Condition when error is raised.

    See Also
    --------
    related_function
    """

Sphinx/reST Style

def function_name(param1, param2):
    """
    Brief description.

    Extended description.

    :param param1: Description of param1.
    :type param1: type
    :param param2: Description of param2.
    :type param2: type
    :returns: Description of return value.
    :rtype: return_type
    :raises ErrorType: Condition when error is raised.
    :see: related_function
    """

Java Javadoc Tags

/**
 * Brief description on first line.
 *
 * Extended description with details.
 *
 * @param paramName Description of parameter
 * @param paramName2 Description of second parameter
 * @return Description of return value
 * @throws ExceptionType Description of when exception is thrown
 * @see RelatedClass#relatedMethod
 * @see #relatedMethod(int, int)
 * @since 1.0
 * @author Author Name
 * @version 1.1
 * @deprecated Use newMethod instead
 * @link https://example.com Related documentation
 */

TypeScript JSDoc Tags

/**
 * Brief description.
 *
 * Extended description.
 *
 * @param paramName - Description of parameter
 * @param paramName2 - Description of second parameter
 * @returns Description of return value
 * @throws {ErrorType} Description of when error is thrown
 * @type TypeName - Type definition
 * @extends ParentType - Inheritance
 * @implements InterfaceName - Interface implementation
 * @example
 * ```typescript
 * const result = functionName(arg1, arg2);
 * ```
 * @see RelatedClass#relatedMethod
 * @since 1.0.0
 * @deprecated Use newFunction instead
 * @see relatedFunction
 */

C# XML Tags

/// <summary>
/// Brief description.
/// </summary>
/// <remarks>
/// Extended description with details.
/// </remarks>
/// <param name="paramName">Description of parameter</param>
/// <param name="paramName2">Description of second parameter</param>
/// <returns>Description of return value</returns>
/// <exception cref="System.Exception">
/// Description of when exception is thrown
/// </exception>
/// <typeparam name="T">Generic type parameter</typeparam>
/// <example>
/// <code>
/// var result = FunctionName(arg1, arg2);
/// </code>
/// </example>
/// <seealso cref="RelatedClass.RelatedMethod"/>
/// <permission cref="System.Security.Permissions">
/// Required permissions
/// </permission>

Special Cases

Generics

Java

/**
 * Processes a list of items.
 *
 * @param <T> The type of items in the list
 * @param items List of items to process
 * @return Processed list of items
 */
public <T> List<T> processItems(List<T> items) {
    // Implementation
}

TypeScript

/**
 * Processes a list of items.
 *
 * @type T - The type of items in the list
 * @param items - List of items to process
 * @returns Processed list of items
 */
function processItems<T>(items: T[]): T[] {
    // Implementation
}

C#

/// <summary>
/// Processes a list of items.
/// </summary>
/// <typeparam name="T">The type of items in the list</typeparam>
/// <param name="items">List of items to process</param>
/// <returns>Processed list of items</returns>
public List<T> ProcessItems<T>(List<T> items) {
    // Implementation
}

Method Overloads

Java

/**
 * Calculates the sum.
 *
 * @param a First integer
 * @param b Second integer
 * @return Sum of two integers
 */
public int calculateSum(int a, int b) {
    return a + b;
}

/**
 * Calculates the sum of three integers.
 *
 * @param a First integer
 * @param b Second integer
 * @param c Third integer
 * @return Sum of three integers
 */
public int calculateSum(int a, int b, int c) {
    return a + b + c;
}

C#

/// <summary>
/// Calculates the sum.
/// </summary>
/// <param name="a">First integer</param>
/// <param name="b">Second integer</param>
/// <returns>Sum of two integers</returns>
public int CalculateSum(int a, int b) {
    return a + b;
}

/// <summary>
/// Calculates the sum of three integers.
/// </summary>
/// <param name="a">First integer</param>
/// <param name="b">Second integer</param>
/// <param name="c">Third integer</param>
/// <returns>Sum of three integers</returns>
public int CalculateSum(int a, int b, int c) {
    return a + b + c;
}

Type Hints

Python (3.5+)

def process_data(
    data: list[dict[str, Any]],
    options: dict[str, Any] | None = None
) -> dict[str, list[Any]]:
    """
    Process data with optional configuration.

    Args:
        data: List of dictionaries containing data entries.
        options: Optional dictionary of configuration options.

    Returns:
        Dictionary with processed data organized by category.
    """
    # Implementation

TypeScript

/**
 * Process data with optional configuration.
 *
 * @type DataItem - Type of items in data array
 * @param data - Array of data items to process
 * @param options - Optional configuration object
 * @returns Processed data organized by category
 */
function processData<DataItem>(
    data: DataItem[],
    options?: Record<string, unknown>
): Record<string, DataItem[]> {
    // Implementation
}

Best Practices

General

Document all public APIs: Functions, classes, methods, properties
Use clear language: Write as if explaining to another developer
Keep descriptions concise: Be thorough but not overly verbose
Follow existing style: Maintain consistency with codebase conventions
Include examples: Show typical usage patterns
Document edge cases: What happens with null, empty, invalid inputs?
Update docstrings: Keep them in sync with code changes
Document exceptions: Clearly state what exceptions can be raised/thrown

Python-Specific

Use triple quotes (
```
"""
```
) for docstrings
Place docstring immediately after function/class definition
Include type hints in function signatures
Use Google style by default (most popular)
Document all parameters, even optional ones
Include type information in Args/Returns sections

Java-Specific

Use
```
/** ... */
```
format for Javadoc
Place docstring immediately before method/class
Document all @param tags (one per parameter)
Use
```
@return
```
for simple types,
```
@returns
```
for complex types
Include @throws for all checked exceptions
Document generics with
```
<T>
```
notation
Add @see for related methods

TypeScript-Specific

Use
```
/** ... */
```
format for JSDoc
Place docstring immediately before function/class
Include type information in @param tags
Use @throws with {Type} for type safety
Document exported members
Include @example blocks for usage
Document generic type parameters with @type

C#-Specific

Use
```
///
```
for single-line XML comments
Use
```
/** ... */
```
for multi-line XML comments
Place docstring immediately before element
Use XML tags for structured documentation
Escape special characters in XML (e.g.,
```
<
```
becomes
```
&lt;
```
)
Document generics with <typeparam>
Include <remarks> for extended descriptions

Common Issues

Python: Indentation Errors

Issue: Docstring indentation doesn't match code indentation

Solution: Use consistent indentation (4 spaces preferred)

def function():
    """Docstring at same indent as code."""
    pass

Java: Missing @param Tags

Issue: Javadoc warnings about missing parameter documentation

Solution: Document all parameters, even if obvious

/**
 * Method description.
 *
 * @param x First parameter
 * @param y Second parameter  <-- Often forgotten
 */
public void method(int x, int y) {
}

TypeScript: Missing Type in @throws

Issue: Type safety lost without exception type

Solution: Always include type in @throws

/**
 * Method description.
 *
 * @throws {Error} When something goes wrong  <-- Good
 */

C#: XML Escaping Issues

Issue: Special characters break XML documentation

Solution: Use HTML entities or CDATA sections

/// <summary>
/// Method with <special> characters  <-- Bad
/// </summary>

/// <summary>
/// Method with &lt;special&gt; characters  <-- Good
/// </summary>

Workflow Integration

PR Creation

Check for missing docstrings during PR creation:

# Find undocumented functions/methdos
for file in $(git diff --name-only); do
    case "$file" in
        *.py)    UNDOC=$(grep -c 'def ' "$file") \
                    - $(grep -c '"""' "$file") ;;
        *.java)   UNDOC=$(grep -c 'public.*(' "$file") \
                    - $(grep -c '/\*\*' "$file") ;;
        *.ts)     UNDOC=$(grep -c 'function' "$file") \
                    - $(grep -c '/\*\*' "$file") ;;
        *.cs)     UNDOC=$(grep -c 'public.*(' "$file") \
                    - $(grep -c '///' "$file") ;;
    esac

    if [[ $UNDOC -gt 0 ]]; then
        echo "Found $UNDOC undocumented items in $file"
    fi
done

Linting Integration

Add docstring validation to linters:

Python:

# Use pydocstyle for style checking
pydocstyle file.py

Java:

# Use Checkstyle for Javadoc validation
checkstyle -c checkstyle_javadoc.xml file.java

TypeScript:

# Use TSDoc linter
tslint --doc file.ts

Code Review Checklist

All public functions have docstrings
All public classes have docstrings
All parameters are documented
Return values are documented
Exceptions are documented
Docstrings follow language conventions
Docstrings are accurate and up-to-date

Troubleshooting Checklist

Before generating docstrings:

Language is correctly detected
File extension is recognized
Docstring style is determined
Existing style in codebase is detected

After generating docstrings:

Docstrings are inserted at correct location
Docstrings follow language conventions
All parameters are documented
Return values are documented
Exceptions are documented
Examples are included (if applicable)
Docstrings are formatted correctly

Related Skills

```
nextjs-standard-setup
```
: For creating standardized Next.js 16 applications with proper documentation standards
```
opencode-skill-creation
```
: For creating OpenCode skills
```
pr-creation-workflow
```
: For adding docstring validation to PR workflow
```
linting-workflow
```
: For enforcing docstring presence in code
```
python-pytest-creator
```
: For generating Python tests with docstrings