Code Documentation

Code Documentation

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

Overview

Create clear, comprehensive code documentation using language-specific standards like JSDoc, Python docstrings, JavaDoc, and inline comments.

When to Use

• Function and class documentation
• JSDoc for JavaScript/TypeScript
• Python docstrings
• JavaDoc for Java
• Inline code comments
• API documentation from code
• Type definitions
• Usage examples in code

Quick Start

Minimal working example:

/**
 * Calculates the total price including tax and discount.
 *
 * @param {number} basePrice - The base price before tax and discount
 * @param {number} taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
 * @param {number} [discount=0] - Optional discount amount
 * @returns {number} The final price after tax and discount
 * @throws {Error} If basePrice or taxRate is negative
 *
 * @example
 * const price = calculateTotalPrice(100, 0.08, 10);
 * console.log(price); // 98
 *
 * @example
 * // Without discount
 * const price = calculateTotalPrice(100, 0.08);
 * console.log(price); // 108
 */
function calculateTotalPrice(basePrice, taxRate, discount = 0) {
  if (basePrice < 0 || taxRate < 0) {
    throw new Error("Price and tax rate must be non-negative");
  }
  return basePrice * (1 + taxRate) - discount;
}

// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the references/ directory:

Best Practices

✅ DO

• Document public APIs thoroughly
• Include usage examples
• Document parameters and return values
• Specify thrown exceptions/errors
• Use language-specific standards (JSDoc, docstrings, etc.)
• Keep comments up-to-date
• Document "why" not "what"
• Include edge cases and gotchas
• Add links to related functions
• Document type definitions
• Use consistent formatting

❌ DON'T

• State the obvious in comments
• Leave commented-out code
• Write misleading comments
• Skip examples for complex functions
• Use vague parameter descriptions
• Forget to update docs when code changes
• Over-comment simple code

Class Documentation

Class Documentation

/**
 * Represents a shopping cart in an e-commerce application.
 * Manages items, calculates totals, and handles checkout operations.
 *
 * @class
 * @example
 * const cart = new ShoppingCart('user123');
 * cart.addItem({ id: 'prod1', name: 'Laptop', price: 999.99 }, 1);
 * console.log(cart.getTotal()); // 999.99
 */
class ShoppingCart {
  /**
   * Creates a new shopping cart instance.
   *
   * @constructor
   * @param {string} userId - The ID of the user who owns this cart
   * @param {Object} [options={}] - Configuration options
   * @param {string} [options.currency='USD'] - Currency code
   * @param {number} [options.taxRate=0] - Tax rate as decimal
   */
  constructor(userId, options = {}) {
    this.userId = userId;
    this.items = [];
    this.currency = options.currency || "USD";
    this.taxRate = options.taxRate || 0;
  }

  /**
   * Adds an item to the cart or increases quantity if already present.
   *
   * @param {Product} product - The product to add
   * @param {number} quantity - Quantity to add (must be positive integer)
   * @returns {CartItem} The added or updated cart item
   * @throws {Error} If quantity is not a positive integer
   *
   * @typedef {Object} Product
   * @property {string} id - Product ID
   * @property {string} name - Product name
   * @property {number} price - Product price
   *
   * @typedef {Object} CartItem
   * @property {Product} product - Product details
   * @property {number} quantity - Item quantity
   * @property {number} subtotal - Item subtotal (price * quantity)
   */
  addItem(product, quantity) {
    if (!Number.isInteger(quantity) || quantity <= 0) {
      throw new Error("Quantity must be a positive integer");
    }

    const existingItem = this.items.find(
      (item) => item.product.id === product.id,
    );

    if (existingItem) {
      existingItem.quantity += quantity;
      existingItem.subtotal =
        existingItem.product.price * existingItem.quantity;
      return existingItem;
    }

    const newItem = {
      product,
      quantity,
      subtotal: product.price * quantity,
    };
    this.items.push(newItem);
    return newItem;
  }

  /**
   * Calculates the total price including tax.
   *
   * @returns {number} Total price with tax
   */
  getTotal() {
    const subtotal = this.items.reduce((sum, item) => sum + item.subtotal, 0);
    return subtotal * (1 + this.taxRate);
  }

  /**
   * Removes all items from the cart.
   *
   * @returns {void}
   */
  clear() {
    this.items = [];
  }
}

Class Documentation

Class Documentation

/**
 * Represents a shopping cart in an e-commerce application.
 * Manages items, calculates totals, and handles checkout operations.
 *
 * @class
 * @example
 * const cart = new ShoppingCart('user123');
 * cart.addItem({ id: 'prod1', name: 'Laptop', price: 999.99 }, 1);
 * console.log(cart.getTotal()); // 999.99
 */
class ShoppingCart {
  /**
   * Creates a new shopping cart instance.
   *
   * @constructor
   * @param {string} userId - The ID of the user who owns this cart
   * @param {Object} [options={}] - Configuration options
   * @param {string} [options.currency='USD'] - Currency code
   * @param {number} [options.taxRate=0] - Tax rate as decimal
   */
  constructor(userId, options = {}) {
    this.userId = userId;
    this.items = [];
    this.currency = options.currency || "USD";
    this.taxRate = options.taxRate || 0;
  }

  /**
   * Adds an item to the cart or increases quantity if already present.
   *
   * @param {Product} product - The product to add
   * @param {number} quantity - Quantity to add (must be positive integer)
   * @returns {CartItem} The added or updated cart item
   * @throws {Error} If quantity is not a positive integer
   *
   * @typedef {Object} Product
   * @property {string} id - Product ID
   * @property {string} name - Product name
   * @property {number} price - Product price
   *
   * @typedef {Object} CartItem
   * @property {Product} product - Product details
   * @property {number} quantity - Item quantity
   * @property {number} subtotal - Item subtotal (price * quantity)
   */
  addItem(product, quantity) {
    if (!Number.isInteger(quantity) || quantity <= 0) {
      throw new Error("Quantity must be a positive integer");
    }

    const existingItem = this.items.find(
      (item) => item.product.id === product.id,
    );

    if (existingItem) {
      existingItem.quantity += quantity;
      existingItem.subtotal =
        existingItem.product.price * existingItem.quantity;
      return existingItem;
    }

    const newItem = {
      product,
      quantity,
      subtotal: product.price * quantity,
    };
    this.items.push(newItem);
    return newItem;
  }

  /**
   * Calculates the total price including tax.
   *
   * @returns {number} Total price with tax
   */
  getTotal() {
    const subtotal = this.items.reduce((sum, item) => sum + item.subtotal, 0);
    return subtotal * (1 + this.taxRate);
  }

  /**
   * Removes all items from the cart.
   *
   * @returns {void}
   */
  clear() {
    this.items = [];
  }
}

Function Documentation

Function Documentation

/**
 * Calculates the total price including tax and discount.
 *
 * @param {number} basePrice - The base price before tax and discount
 * @param {number} taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
 * @param {number} [discount=0] - Optional discount amount
 * @returns {number} The final price after tax and discount
 * @throws {Error} If basePrice or taxRate is negative
 *
 * @example
 * const price = calculateTotalPrice(100, 0.08, 10);
 * console.log(price); // 98
 *
 * @example
 * // Without discount
 * const price = calculateTotalPrice(100, 0.08);
 * console.log(price); // 108
 */
function calculateTotalPrice(basePrice, taxRate, discount = 0) {
  if (basePrice < 0 || taxRate < 0) {
    throw new Error("Price and tax rate must be non-negative");
  }
  return basePrice * (1 + taxRate) - discount;
}

/**
 * Fetches user data from the API with retry logic.
 *
 * @async
 * @param {string} userId - The unique identifier for the user
 * @param {Object} [options={}] - Additional options
 * @param {number} [options.maxRetries=3] - Maximum number of retry attempts
 * @param {number} [options.timeout=5000] - Request timeout in milliseconds
 * @returns {Promise<User>} Promise resolving to user object
 * @throws {Error} If user not found after all retries
 *
 * @typedef {Object} User
 * @property {string} id - User ID
 * @property {string} name - User's full name
 * @property {string} email - User's email address
 * @property {string[]} roles - Array of user roles
 *
 * @example
 * try {
 *   const user = await fetchUser('user123', { maxRetries: 5 });
 *   console.log(user.name);
 * } catch (error) {
 *   console.error('Failed to fetch user:', error);
 * }
 */
async function fetchUser(userId, options = {}) {
  const { maxRetries = 3, timeout = 5000 } = options;
  // Implementation...
}

Function Documentation

Function Documentation

/**
 * Calculates the total price including tax and discount.
 *
 * @param {number} basePrice - The base price before tax and discount
 * @param {number} taxRate - Tax rate as a decimal (e.g., 0.08 for 8%)
 * @param {number} [discount=0] - Optional discount amount
 * @returns {number} The final price after tax and discount
 * @throws {Error} If basePrice or taxRate is negative
 *
 * @example
 * const price = calculateTotalPrice(100, 0.08, 10);
 * console.log(price); // 98
 *
 * @example
 * // Without discount
 * const price = calculateTotalPrice(100, 0.08);
 * console.log(price); // 108
 */
function calculateTotalPrice(basePrice, taxRate, discount = 0) {
  if (basePrice < 0 || taxRate < 0) {
    throw new Error("Price and tax rate must be non-negative");
  }
  return basePrice * (1 + taxRate) - discount;
}

/**
 * Fetches user data from the API with retry logic.
 *
 * @async
 * @param {string} userId - The unique identifier for the user
 * @param {Object} [options={}] - Additional options
 * @param {number} [options.maxRetries=3] - Maximum number of retry attempts
 * @param {number} [options.timeout=5000] - Request timeout in milliseconds
 * @returns {Promise<User>} Promise resolving to user object
 * @throws {Error} If user not found after all retries
 *
 * @typedef {Object} User
 * @property {string} id - User ID
 * @property {string} name - User's full name
 * @property {string} email - User's email address
 * @property {string[]} roles - Array of user roles
 *
 * @example
 * try {
 *   const user = await fetchUser('user123', { maxRetries: 5 });
 *   console.log(user.name);
 * } catch (error) {
 *   console.error('Failed to fetch user:', error);
 * }
 */
async function fetchUser(userId, options = {}) {
  const { maxRetries = 3, timeout = 5000 } = options;
  // Implementation...
}

Module Documentation

Module Documentation

"""
User authentication and authorization module.

This module provides functions for user authentication, password hashing,
token generation, and permission checking. It supports multiple authentication
methods including JWT tokens, API keys, and OAuth2.

Features:
    - Secure password hashing with bcrypt
    - JWT token generation and validation
    - Role-based access control (RBAC)
    - OAuth2 integration (Google, GitHub)
    - Two-factor authentication (2FA)

Example:
    Basic authentication:

    >>> from auth import authenticate, generate_token
    >>> user = authenticate('user@example.com', 'password123')
    >>> token = generate_token(user)

    Password hashing:

    >>> from auth import hash_password, verify_password
    >>> hashed = hash_password('password123')
    >>> is_valid = verify_password('password123', hashed)

Attributes:
    TOKEN_EXPIRY (int): Default token expiration time in seconds
    HASH_ROUNDS (int): Number of bcrypt hashing rounds
    MAX_LOGIN_ATTEMPTS (int): Maximum failed login attempts before lockout

Todo:
    * Add support for SAML authentication
    * Implement refresh token rotation
    * Add rate limiting for login attempts

Note:
    This module requires bcrypt and PyJWT packages to be installed.
"""

TOKEN_EXPIRY = 3600  # 1 hour
HASH_ROUNDS = 12
MAX_LOGIN_ATTEMPTS = 5

Type Definitions

Type Definitions

/**
 * API response wrapper for all endpoints
 *
 * @template T - The type of data in the response
 * @typedef {Object} ApiResponse
 * @property {boolean} success - Whether the request succeeded
 * @property {T} [data] - Response data (present on success)
 * @property {string} [error] - Error message (present on failure)
 * @property {Object} [metadata] - Additional response metadata
 * @property {number} metadata.timestamp - Response timestamp
 * @property {string} metadata.requestId - Unique request ID
 */

/**
 * User authentication credentials
 *
 * @typedef {Object} Credentials
 * @property {string} email - User email address
 * @property {string} password - User password (min 8 characters)
 */

/**
 * Pagination parameters for list endpoints
 *
 * @typedef {Object} PaginationParams
 * @property {number} [page=1] - Page number (1-indexed)
 * @property {number} [limit=20] - Items per page (max 100)
 * @property {string} [sortBy='createdAt'] - Field to sort by
 * @property {'asc'|'desc'} [order='desc'] - Sort order
 */

Document Title

Overview

TODO: Brief description of this document's purpose.

Prerequisites

• TODO: List prerequisites

Getting Started

TODO: Step-by-step instructions.

Configuration

TODO: Configuration details.

Examples

TODO: Add practical examples.

Troubleshooting

TODO: Common issues and solutions.

References

• TODO: Add relevant links