docstrings

name: docstrings description: Generate comprehensive function, class, and module docstrings following language conventions (JSDoc, PyDoc, JavaDoc, XML docs, godoc, Doxygen). Use when documenting APIs, adding inline documentation, improving code discoverability, or generating API reference documentation. summary_l0: "Generate standards-compliant docstrings in JSDoc, PyDoc, JavaDoc, and godoc formats" overview_l1: "This skill generates comprehensive, standards-compliant docstrings for all public interfaces including modules, classes, functions, and methods. Use it when documenting function parameters and return values, adding class and module documentation, generating API reference documentation, improving code discoverability, creating self-documenting code, or meeting documentation requirements. Key capabilities include multi-format docstring generation (JSDoc for JavaScript/TypeScript, PyDoc/Google/NumPy style for Python, JavaDoc for Java, XML docs for C#, godoc for Go, Doxygen for C/C++), parameter and return type documentation, exception documentation, usage example generation, and deprecation notice formatting. The expected output is properly formatted docstrings following language-specific conventions with parameter descriptions, return values, exceptions, and usage examples. Trigger phrases: add docstrings, document code, generate docstrings, API documentation, JSDoc, PyDoc, JavaDoc, godoc, Doxygen."

Docstring Generation

Generate comprehensive, standards-compliant docstrings for all public interfaces including modules, classes, functions, and methods.

When to Use This Skill

Use this skill when you need to:

• Document function parameters and return values
• Add class and module documentation
• Generate API reference documentation
• Improve code discoverability
• Create self-documenting code
• Meet documentation requirements

Trigger phrases: "add docstrings", "document code", "generate docstrings", "API documentation", "JSDoc", "PyDoc", "JavaDoc", "godoc", "Doxygen"

What This Skill Does

Documentation Formats by Language

Instructions

Python Docstrings (Google Style)

"""Module-level docstring describing the module's purpose.

This module provides utility functions for data processing
and validation. It supports multiple input formats and
includes comprehensive error handling.

Example:
    >>> from mymodule import process_data
    >>> result = process_data({"key": "value"})
    >>> print(result)
    {'key': 'VALUE'}

Attributes:
    DEFAULT_CONFIG (dict): Default configuration settings.
    SUPPORTED_FORMATS (list): List of supported file formats.
"""

def process_data(
    data: dict[str, Any],
    options: dict[str, Any] | None = None,
    *,
    strict: bool = False
) -> dict[str, Any]:
    """Process and transform input data according to rules.

    Validates input data, applies transformations based on
    configuration, and returns the processed result.

    Args:
        data: Input data dictionary to process.
        options: Optional processing options. Defaults to None.
        strict: If True, raise on warnings. Defaults to False.

    Returns:
        Processed data dictionary with transformations applied.

    Raises:
        ValueError: If data is empty or malformed.
        TypeError: If data is not a dictionary.
        ProcessingError: If transformation fails.

    Example:
        >>> result = process_data({"name": "test"})
        >>> print(result)
        {'name': 'TEST'}

    Note:
        This function modifies the input data in place when
        `options['in_place']` is True.
    """
    pass


class DataProcessor:
    """A class for processing and transforming data.

    This class provides methods for validating, transforming,
    and exporting data in various formats.

    Attributes:
        config: Configuration dictionary for processing.
        logger: Logger instance for this processor.

    Example:
        >>> processor = DataProcessor(config={'format': 'json'})
        >>> result = processor.process(data)
    """

    def __init__(self, config: dict[str, Any]) -> None:
        """Initialize the DataProcessor.

        Args:
            config: Configuration dictionary containing:
                - format (str): Output format ('json', 'csv')
                - validate (bool): Enable validation
                - strict (bool): Strict mode
        """
        pass

JavaScript/TypeScript (JSDoc)

/**
 * Module for data processing utilities.
 * @module dataProcessor
 */

/**
 * Process and transform input data.
 *
 * @param {Object} data - Input data to process
 * @param {string} data.name - Name field
 * @param {number} data.value - Value field
 * @param {Object} [options={}] - Processing options
 * @param {boolean} [options.strict=false] - Enable strict mode
 * @returns {Promise<Object>} Processed data object
 * @throws {ValidationError} If data validation fails
 * @throws {ProcessingError} If transformation fails
 *
 * @example
 * const result = await processData({ name: 'test', value: 42 });
 * console.log(result);
 * // { name: 'TEST', value: 42, processed: true }
 */
async function processData(data, options = {}) {
  // Implementation
}

/**
 * Data processor class for handling transformations.
 *
 * @class
 * @classdesc Provides methods for data validation and transformation.
 *
 * @example
 * const processor = new DataProcessor({ format: 'json' });
 * const result = processor.process(data);
 */
class DataProcessor {
  /**
   * Create a new DataProcessor.
   *
   * @param {Object} config - Configuration object
   * @param {string} config.format - Output format
   * @param {boolean} [config.validate=true] - Enable validation
   */
  constructor(config) {
    /** @type {Object} Configuration settings */
    this.config = config;
  }

  /**
   * Process the input data.
   *
   * @param {Object} data - Data to process
   * @returns {Object} Processed data
   * @memberof DataProcessor
   */
  process(data) {
    // Implementation
  }
}

Java (JavaDoc)

/**
 * Data processing utility class.
 *
 * <p>This class provides methods for validating, transforming,
 * and exporting data in various formats.</p>
 *
 * <p>Example usage:</p>
 * <pre>{@code
 * DataProcessor processor = new DataProcessor(config);
 * Result result = processor.process(data);
 * }</pre>
 *
 * @author Your Name
 * @version 1.0
 * @since 1.0
 * @see DataValidator
 * @see TransformationEngine
 */
public class DataProcessor {

    /**
     * Process and transform input data.
     *
     * <p>Validates the input, applies configured transformations,
     * and returns the processed result.</p>
     *
     * @param data the input data map to process
     * @param options optional processing configuration
     * @return processed data as a new map
     * @throws IllegalArgumentException if data is null or empty
     * @throws ProcessingException if transformation fails
     *
     * @see #validate(Map)
     * @since 1.0
     */
    public Map<String, Object> processData(
            Map<String, Object> data,
            ProcessingOptions options) throws ProcessingException {
        // Implementation
    }
}

C# (XML Documentation)

/// <summary>
/// Provides data processing and transformation capabilities.
/// </summary>
/// <remarks>
/// This class handles validation, transformation, and export
/// of data in various formats.
/// </remarks>
/// <example>
/// <code>
/// var processor = new DataProcessor(config);
/// var result = processor.Process(data);
/// </code>
/// </example>
public class DataProcessor
{
    /// <summary>
    /// Processes and transforms the input data.
    /// </summary>
    /// <param name="data">The input data dictionary to process.</param>
    /// <param name="options">Optional processing configuration.</param>
    /// <returns>
    /// A dictionary containing the processed data.
    /// </returns>
    /// <exception cref="ArgumentNullException">
    /// Thrown when <paramref name="data"/> is null.
    /// </exception>
    /// <exception cref="ProcessingException">
    /// Thrown when transformation fails.
    /// </exception>
    /// <seealso cref="Validate"/>
    public Dictionary<string, object> Process(
        Dictionary<string, object> data,
        ProcessingOptions options = null)
    {
        // Implementation
    }
}

Go (godoc)

// Package processor provides data processing utilities.
//
// This package contains functions and types for validating,
// transforming, and exporting data in various formats.
//
// Example:
//
//	processor := NewProcessor(config)
//	result, err := processor.Process(data)
//	if err != nil {
//	    log.Fatal(err)
//	}
package processor

// Processor handles data transformation operations.
type Processor struct {
    config Config
    logger *log.Logger
}

// NewProcessor creates a new Processor with the given configuration.
//
// The config parameter specifies processing options including
// output format, validation settings, and transformation rules.
func NewProcessor(config Config) *Processor {
    return &Processor{config: config}
}

// Process transforms the input data according to configuration.
//
// It validates the input, applies transformations, and returns
// the processed result. If validation or transformation fails,
// an error is returned.
//
// Example:
//
//	result, err := processor.Process(map[string]interface{}{
//	    "name": "test",
//	    "value": 42,
//	})
func (p *Processor) Process(data map[string]interface{}) (map[string]interface{}, error) {
    // Implementation
}

C/C++ (Doxygen)

/**
 * @file processor.h
 * @brief Data processing utilities
 * @author Your Name
 * @date 2025-12-08
 *
 * This module provides functions for data validation,
 * transformation, and export in various formats.
 */

/**
 * @brief Data processor class for handling transformations.
 *
 * This class provides methods for validating, transforming,
 * and exporting data. It supports multiple output formats
 * and includes comprehensive error handling.
 *
 * @code
 * Processor proc(config);
 * auto result = proc.process(data);
 * @endcode
 */
class Processor {
public:
    /**
     * @brief Process and transform input data.
     *
     * Validates the input data, applies configured transformations,
     * and returns the processed result.
     *
     * @param[in] data Input data to process
     * @param[in] options Processing options (optional)
     * @param[out] result Pointer to store the result
     * @return Status code (0 for success)
     * @retval 0 Success
     * @retval -1 Validation error
     * @retval -2 Transformation error
     *
     * @throws std::invalid_argument if data is null
     * @throws ProcessingException if transformation fails
     *
     * @pre data must not be null
     * @post result contains transformed data on success
     *
     * @see validate()
     * @since 1.0
     */
    int process(const Data* data, const Options* options, Result* result);
};

Common Rationalizations

Verification

• All public modules/packages documented
• All public classes documented
• All public functions/methods documented
• Parameters clearly described
• Return values documented
• Exceptions/errors documented
• Examples provided for complex APIs
• Type information included
• Consistent style throughout
• Documentation builds without errors

Common Issues and Solutions

Issue: Missing type information

Solution: Include type hints in function signatures and docstrings:

def process(data: dict[str, Any]) -> Result:
    """Process data.

    Args:
        data: Input dictionary with string keys.

    Returns:
        Result object containing processed data.
    """

Issue: Docstring doesn't match signature

Solution: Keep docstrings synchronized with code changes and use tools to validate.

Issue: Examples don't work

Solution: Use doctest to verify examples:

python -m doctest module.py

Related Skills

• [[strategic-comments]] - High-value code comments
• [[api-documentation]] - API reference documentation
• [[user-documentation]] - User guides and tutorials

Version: 1.0.0 Last Updated: December 2025 Based on: AI Templates documentation_generation/docstrings/

Iterative Refinement Strategy

This skill is optimized for an iterative approach:

1. Execute: Perform the core steps defined above.
2. Review: Critically analyze the output (coverage, quality, completeness).
3. Refine: If targets aren't met, repeat the specific implementation steps with improved context.
4. Loop: Continue until the definition of done is satisfied.