thebushidocollective/han/document

/document [arguments]

# Project Name
 
Brief description (one paragraph) of what this project does and why it exists.
 
## Features
 
-Feature 1
-Feature 2
-Feature 3
 
## Installation
 

 
## Quick Start
 

 
## Usage
 
### Basic Usage
 
[Most common use case with complete example]
 
### Advanced Usage
 
[More complex scenarios]
 
## API Reference
 
### `functionName(param1, param2)`
 
Description of what the function does.
 
**Parameters:**
 
- `param1` (string, required): Description of parameter
- `param2` (number, optional): Description with default. Default: 42
 
**Returns:** `string` - Description of return value
 
**Throws:**
 
- `Error` - When parameter is invalid
 
**Example:**
 

 
## Configuration
 
[How to configure, if applicable]
 
## Troubleshooting
 
### Error: "Cannot find module"
 
**Cause:** Package not installed
**Solution:**
 

 
## Contributing
 
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
## License
 
MIT License - see [LICENSE](LICENSE) file for details.
 

## POST /api/users
 
Create a new user account.
 
### Authentication
 
Requires admin access token in Authorization header.
 
### Request
 
**Headers:**

 
**Body:**
 

 
**Body Parameters:**
 
- `email` (string, required): Valid email address. Must be unique.
- `name` (string, required): User's full name. 2-100 characters.
- `role` (string, optional): User role. One of: "user", "admin". Default: "user".
 
### Response
 
**Success (201 Created):**
 

 
**Error Responses:**
 
**400 Bad Request:**
 

 
**401 Unauthorized:**
 

 
**403 Forbidden:**
 

 
**409 Conflict:**
 

 
**429 Too Many Requests:**
 

 
### Example
 
**cURL:**
 

 
**JavaScript:**
 

 
### Rate Limiting
 
- 100 requests per minute per API key
- Returns 429 when exceeded
- Check `X-RateLimit-Remaining` header
 

/**
 * Calculate the total price including tax and shipping.
 *
 * Tax is calculated on the subtotal, not including shipping.
 * Free shipping is applied for orders over $50.
 *
 * @param items - Array of cart items with price and quantity
 * @param shippingAddress - Shipping address for tax calculation
 * @returns Object containing subtotal, tax, shipping, and total
 *
 * @throws {Error} If items array is empty
 * @throws {Error} If any item has invalid price or quantity
 *
 * @example
 * ```typescript
 * const total = calculateTotal([
 *   { price: 10, quantity: 2 },
 *   { price: 15, quantity: 1 }
 * ], { state: 'CA' })
 *
 * console.log(total)
 * // {
 * //   subtotal: 35,
 * //   tax: 2.80,
 * //   shipping: 0,
 * //   total: 37.80
 * // }
 * ```
 */
function calculateTotal(
  items: CartItem[],
  shippingAddress: Address
): OrderTotal {
  // Implementation...
}

// BAD: States the obvious
// Loop through users
for (const user of users) {
  // Print user name
  console.log(user.name)
}
// GOOD: Explains why
// Process in creation order to maintain referential integrity
// (newer records may reference older ones)
for (const user of users.sort((a, b) => a.createdAt - b.createdAt)) {
  processUser(user)
}
// BAD: Redundant
// Add 1 to counter
counter = counter + 1
// GOOD: Explains non-obvious decision
// +1 offset because API uses 1-based indexing (not 0-based)
const pageNumber = index + 1
// BAD: Explains what (obvious)
function calculateTotal(price, quantity) {
  // Multiply price by quantity
  return price * quantity
}
// GOOD: Explains why (non-obvious)
function calculateTotal(price, quantity) {
  // Use Number.toFixed(2) to prevent floating point errors
  // (0.1 + 0.2 !== 0.3 in JavaScript)
  return Number((price * quantity).toFixed(2))
}
// BAD: Commented-out code
function processOrder(order) {
  // const tax = order.subtotal * 0.08
  const tax = calculateTax(order)
  return order.subtotal + tax
}
// GOOD: Explains temporary workaround
function processOrder(order) {
  // TODO: Remove when new tax API is deployed (JIRA-123)
  // Using hardcoded rate temporarily during migration
  const tax = order.subtotal * 0.08
  return order.subtotal + tax
}

// For brief explanations
const tax = subtotal * TAX_RATE  // Updated quarterly

/*
 * For longer explanations that span multiple lines.
 * Use when context requires more detail.
 */

/**
 * For API documentation.
 * Parsed by documentation generators.
 * @param name - Parameter description
 * @returns Return value description
 */

// TODO(username): Description of what needs to be done
// FIXME: Description of what's broken and needs fixing
// HACK: Description of temporary workaround
// NOTE: Important information to highlight

# How to [Task Name]
 
Brief description of what this guide teaches and who should use it.
 
## Prerequisites
 
-Requirement 1
-Requirement 2
-Knowledge/tools needed
 
## Overview
 
High-level explanation of the process or concept.
 
## Step-by-Step Instructions
 
### Step 1: [First Action]
 
Detailed description of what to do.
 

 
**Expected result:** What you should see.
 
**If something goes wrong:** How to troubleshoot.
 
### Step 2: [Next Action]
 
[Continue with clear steps...]
 
## Example
 
Complete working example showing the entire process.
 

 
## Common Issues
 
### Issue: [Problem Description]
 
**Symptom:** What you see when this happens.
**Cause:** Why it happens.
**Solution:** How to fix it.
 
## Related Documentation
 
- [Link to related guide]
- [Link to API docs]
 
## Next Steps
 
- [What to do after completing this guide]
 

# ADR-###: [Decision Title]
 
**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** YYYY-MM-DD
**Deciders:** [Names of decision makers]
 
## Context
 
What is the issue we're trying to solve? What factors are at play?
What constraints exist?
 
## Decision
 
What did we decide to do?
 
## Alternatives Considered
 
### Alternative 1: [Name]
 
**Description:** Brief explanation
 
**Pros:**
-Advantage 1
-Advantage 2
 
**Cons:**
-Disadvantage 1
-Disadvantage 2
 
**Why not chosen:** Explanation
 
### Alternative 2: [Name]
 
[Same structure...]
 
## Consequences
 
### Positive
 
-Benefit 1
-Benefit 2
 
### Negative
 
-Drawback 1
-Drawback 2
 
### Neutral
 
-Trade-off 1
-Trade-off 2
 
## Implementation Notes
 
Any specific guidance for implementing this decision.
 
## References
 
-[Related documentation]
-[Discussion links]
-[Research sources]

The function accepts parameters and returns a result.

function calculateTotal(items, tax) {
  return items.reduce((sum, item) => sum + item.price, 0) * (1 + tax)
}
// Example usage:
const items = [{ price: 10 }, { price: 20 }]
const total = calculateTotal(items, 0.08) // 32.40