Code Documentation Generator

Эксперт по созданию качественной документации кода.

Основные принципы

• Clarity > Sophistication — ясность важнее сложности

• Progressive disclosure — от общего к деталям

• Consistency — единообразие форматирования

• Accuracy — синхронизация с кодом

• Accessibility — для разных уровней разработчиков

JSDoc (JavaScript/TypeScript)

/**

• Calculates the total price including tax and discounts.
• @param {number} basePrice - The original price before modifications
• @param {number} taxRate - Tax rate as decimal (e.g., 0.21 for 21%)
• @param {number} [discount=0] - Optional discount as decimal
• @returns {number} The final calculated price
• @throws {Error} If basePrice or taxRate is negative
• @example
• // Calculate price with 21% tax and 10% discount
• const total = calculateTotalPrice(100, 0.21, 0.10);
• // Returns: 108.90 */ function calculateTotalPrice(basePrice, taxRate, discount = 0) { if (basePrice < 0 || taxRate < 0) { throw new Error('Price and tax rate must be non-negative'); } const discountedPrice = basePrice * (1 - discount); return discountedPrice * (1 + taxRate); }

TypeScript с JSDoc

/**

• User service for managing user operations. / export class UserService { /*
  • Creates a new user in the system.
  • @param userData - The user data for registration
  • @returns Promise resolving to the created user
  • @throws {ValidationError} When user data is invalid
  • @throws {DuplicateError} When email already exists
  • @example
  • const user = await userService.createUser({
  • email: 'user@example.com',
  • name: 'John Doe'
  • }); */ async createUser(userData: CreateUserDTO): Promise<User> { // Implementation }

/**

• Retrieves a user by their unique identifier.
• @param id - The user's UUID
• @returns The user if found, null otherwise */ async getUserById(id: string): Promise<User | null> { // Implementation } }

Python Docstrings (Google Style)

def process_transaction( amount: float, currency: str, metadata: dict | None = None ) -> TransactionResult: """Process a financial transaction with validation and logging.

This function handles the complete transaction lifecycle including
validation, processing, and audit logging. It supports multiple
currencies and optional metadata attachment.

Args:
    amount: The transaction amount in the specified currency.
        Must be positive and not exceed the daily limit.
    currency: ISO 4217 currency code (e.g., 'USD', 'EUR').
    metadata: Optional dictionary with additional transaction
        details. Keys 'reference' and 'notes' are recommended.

Returns:
    TransactionResult containing:
        - transaction_id: Unique identifier for the transaction
        - status: 'completed', 'pending', or 'failed'
        - timestamp: UTC datetime of processing
        - fee: Applied transaction fee

Raises:
    ValidationError: If amount is negative or exceeds limits.
    CurrencyNotSupportedError: If currency code is invalid.
    InsufficientFundsError: If account balance is too low.

Example:
    >>> result = process_transaction(
    ...     amount=100.50,
    ...     currency='USD',
    ...     metadata={'reference': 'INV-001'}
    ... )
    >>> print(result.transaction_id)
    'txn_abc123xyz'

Note:
    Transactions over $10,000 require additional verification
    and may be held for compliance review.
"""
pass

Python Docstrings (NumPy Style)

def calculate_statistics( data: np.ndarray, weights: np.ndarray | None = None, axis: int = 0 ) -> dict: """ Calculate weighted statistics for the input data.

Parameters
----------
data : np.ndarray
    Input data array of shape (n_samples, n_features).
weights : np.ndarray, optional
    Weight array of shape (n_samples,). If None, uniform
    weights are used.
axis : int, default=0
    Axis along which to compute statistics.

Returns
-------
dict
    Dictionary containing:
    - 'mean' : np.ndarray
        Weighted mean values.
    - 'std' : np.ndarray
        Weighted standard deviation.
    - 'median' : np.ndarray
        Weighted median values.

Raises
------
ValueError
    If data and weights have incompatible shapes.
TypeError
    If data is not a numpy array.

See Also
--------
numpy.average : Compute weighted average.
scipy.stats.describe : Compute descriptive statistics.

Examples
--------
>>> data = np.array([[1, 2], [3, 4], [5, 6]])
>>> stats = calculate_statistics(data)
>>> stats['mean']
array([3., 4.])
"""
pass

REST API Documentation

OpenAPI/Swagger style

paths: /api/users: post: summary: Create a new user description: | Creates a new user account with the provided information. Email must be unique across the system. tags: - Users security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUserRequest' example: email: "user@example.com" name: "John Doe" role: "member" responses: '201': description: User created successfully content: application/json: schema: $ref: '#/components/schemas/User' '400': description: Invalid request data '409': description: Email already exists

Markdown API Documentation

Create User

Creates a new user account.

Endpoint: POST /api/users

Authentication: Bearer token required

Request Body

Example Request

{
  "email": "user@example.com",
  "name": "John Doe",
  "role": "member"
}

Response

201 Created

{
  "id": "usr_abc123",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "member",
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses

Code
Description

400
Invalid request data

401
Unauthorized

409
Email already exists

## README Template

```markdown
# Project Name

Brief description of what this project does.

## Features

- Feature 1
- Feature 2
- Feature 3

## Quick Start

```bash
npm install project-name

import { Client } from 'project-name';

const client = new Client({ apiKey: 'your-key' });
const result = await client.doSomething();

Prerequisites

- Node.js 18+

- npm 8+

Installation

# Using npm
npm install project-name

# Using yarn
yarn add project-name

Configuration

Variable
Default
Description

API_KEY
-
Your API key (required)

TIMEOUT
30000
Request timeout in ms

DEBUG
false
Enable debug logging

Contributing

See CONTRIBUTING.md

License

MIT

## Inline Comments

```javascript
// GOOD: Explain WHY, not WHAT
// Skip validation for internal requests to improve performance
// External requests are validated at the API gateway
if (request.isInternal) {
  return processDirectly(data);
}

// BAD: States the obvious
// Check if user is null
if (user === null) {
  return null;
}

// GOOD: Document complex logic
// Using binary search for O(log n) lookup in sorted array
// Linear search would be O(n) for 10k+ items
const index = binarySearch(sortedItems, targetId);

// GOOD: Explain business rules
// Orders over $1000 require manager approval per policy DOC-123
// This threshold was set by finance team in Q3 2023
if (order.total > 1000 && !order.hasManagerApproval) {
  throw new ApprovalRequiredError();
}

Автоматизация документации

TypeDoc

{
  "typedocOptions": {
    "entryPoints": ["src/index.ts"],
    "out": "docs",
    "plugin": ["typedoc-plugin-markdown"],
    "readme": "README.md",
    "excludePrivate": true,
    "excludeInternal": true
  }
}

Sphinx (Python)

# conf.py
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'sphinx_autodoc_typehints'
]

autodoc_default_options = {
    'members': True,
    'undoc-members': True,
    'show-inheritance': True
}

Лучшие практики

- Документируйте публичный API — всё, что экспортируется

- Примеры кода — реальные use cases

- Обновляйте синхронно — документация = часть PR

- Используйте линтеры — eslint-plugin-jsdoc, pydocstyle

- Версионируйте — документация должна соответствовать версии кода