Learn Python docstring conventions and best practices. Write clear, consistent function and class documentation following industry standards.
Python documentation follows Triple-quoted strings with various formats (Google, NumPy, Sphinx). Common tools like Sphinx and pydoc help generate and maintain Python documentation.
Start with a clear, concise one-line summary of what the function or class does. Use present tense and action verbs. Follow with a more detailed explanation if needed.
/**
* Calculate the total price including tax and shipping.
*
* This function applies the appropriate tax rate based on
* the customer's location and adds shipping costs.
*/
Document each parameter with its name, type, and purpose. Include whether it's optional and any default values. Explain valid ranges or acceptable values.
* @param {number} subtotal - The pre-tax total amount
* @param {string} location - Customer's country code (ISO 3166)
* @param {Object} options - Optional configuration
* @param {boolean} [options.express=false] - Use express shipping
Specify what the function returns, including the type and a description of the value. For complex return types, document the structure.
* @returns {Object} Pricing breakdown
* @returns {number} returns.total - Final total with tax and shipping
* @returns {number} returns.tax - Tax amount applied
* @returns {number} returns.shipping - Shipping cost
Document any exceptions or errors that might be thrown, including when and why they occur. This helps users handle errors properly.
* @throws {ValidationError} If subtotal is negative
* @throws {LocationError} If location code is invalid
* @throws {ConfigError} If required tax config is missing
Provide clear examples showing how to use the function or class. Include common use cases and edge cases when helpful.
* @example
* // Calculate total for US customer
* const result = calculateTotal(99.99, 'US');
* console.log(result.total); // 107.99
*
* @example
* // With express shipping
* const result = calculateTotal(99.99, 'US', \{ express: true \});
Include other relevant information like deprecation notices, version history, related functions, or links to external resources.
* @since 2.0.0
* @see \{@link applyDiscount\} for discount calculations
* @deprecated Use calculateTotalV2() instead
* @author John Doe
Generate professional docstrings for your Python code with DocuWriter.ai
View examplesWant to learn more? Check out our guide on technical documentation best practices
FAQ
A docstring is a string literal that appears as the first statement in a module, function, class, or method to document what it does and how to use it.
Include a brief description, parameters with types, return values, exceptions raised, and usage examples when helpful.
Yes, common formats include JSDoc for JavaScript, PHPDoc for PHP, Javadoc for Java, and various styles for Python (Google, NumPy, reStructuredText).
Related resources
Get started
Start documenting and organizing your codebase