api-documentation

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: api-documentation
description: Best practices for documenting APIs and code interfaces, eliminating redundant documentation guidance per agent.
user-invocable: false
disable-model-invocation: true
updated_at: 2025-10-30T17:00:00Z
tags: [api, documentation, best-practices, interfaces]
progressive_disclosure:
  entry_point:
    summary: "Best practices for documenting APIs and code interfaces, eliminating redundant documentation guidance per agent."
    when_to_use: "When designing, implementing, or documenting APIs."
    quick_start: "1. Review the core concepts below. 2. Apply patterns to your use case. 3. Follow best practices for implementation."
---
# API Documentation

Best practices for documenting APIs and code interfaces. Eliminates ~100-150 lines of redundant documentation guidance per agent.

## Core Documentation Principles

1. **Document the why, not just the what** - Explain intent and rationale
2. **Keep docs close to code** - Inline documentation stays synchronized
3. **Document contracts, not implementation** - Focus on behavior
4. **Examples are essential** - Show real usage
5. **Update docs with code** - Outdated docs are worse than no docs

## Function/Method Documentation

### Python (Docstrings)

```python
def calculate_discount(price: float, discount_percent: float) -> float:
    """
    Calculate discounted price with percentage off.

    Args:
        price: Original price in dollars (must be positive)
        discount_percent: Discount percentage (0-100)

    Returns:
        Final price after discount, rounded to 2 decimals

    Raises:
        ValueError: If price is negative or discount > 100

    Examples:
        >>> calculate_discount(100.0, 20.0)
        80.0
        >>> calculate_discount(50.0, 50.0)
        25.0

    Note:
        Discount percent is capped at 100% (minimum price of 0)
    """
    if price < 0:
        raise ValueError("Price cannot be negative")
    if discount_percent > 100:
        raise ValueError("Discount cannot exceed 100%")

    discount_amount = price * (discount_percent / 100)
    return round(price - discount_amount, 2)
```

### JavaScript (JSDoc)

```javascript
/**
 * Calculate discounted price with percentage off
 *
 * @param {number} price - Original price in dollars (must be positive)
 * @param {number} discountPercent - Discount percentage (0-100)
 * @returns {number} Final price after discount, rounded to 2 decimals
 * @throws {Error} If price is negative or discount > 100
 *
 * @example
 * calculateDiscount(100.0, 20.0)
 * // returns 80.0
 *
 * @example
 * calculateDiscount(50.0, 50.0)
 * // returns 25.0
 */
function calculateDiscount(price, discountPercent) {
  if (price < 0) {
    throw new Error('Price cannot be negative');
  }
  if (discountPercent > 100) {
    throw new Error('Discount cannot exceed 100%');
  }

  const discountAmount = price * (discountPercent / 100);
  return Math.round((price - discountAmount) * 100) / 100;
}
```

### Go (Godoc)

```go
// CalculateDiscount calculates discounted price with percentage off.
//
// The function applies the given discount percentage to the original price
// and returns the final price rounded to 2 decimal places.
//
// Parameters:
//   - price: Original price in dollars (must be positive)
//   - discountPercent: Discount percentage (0-100)
//
// Returns the final price after discount.
//
// Returns an error if price is negative or discount exceeds 100%.
//
// Example:
//
//	finalPrice, err := CalculateDiscount(100.0, 20.0)
//	// finalPrice = 80.0
func CalculateDiscount(price, discountPercent float64) (float64, error) {
    if price < 0 {
        return 0, errors.New("price cannot be negative")
    }
    if discountPercent > 100 {
        return 0, errors.New("discount cannot exceed 100%")
    }

    discountAmount := price * (discountPercent / 100)
    return math.Round((price-discountAmount)*100) / 100, nil
}
```

## API Endpoint Documentation

### REST API (OpenAPI/Swagger)

```yaml
openapi: 3.0.