Add comprehensive API documentation

- Add detailed API reference with examples for all core functions
- Include format(), parse(), subtract(), and other function docs
- Add FormatterOptions and ParserOptions documentation
- Include format tokens reference and usage examples

Author: knowledgecode

docs/api/addDays.md

@@ -0,0 +1,128 @@
+# addDays()
+
+Adds or subtracts days from a Date object. Handles month boundaries, leap years, and daylight saving time transitions properly.
+
+## Syntax
+
+```typescript
+addDays(dateObj, days[, timeZone])
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `dateObj` | `Date` | Yes | The base Date object |
+| `days` | `number` | Yes | Number of days to add (positive) or subtract (negative) |
+| `timeZone` | `TimeZone \| 'UTC'` | No | Timezone for the calculation |
+
+### Returns
+
+`Date` - A new Date object with the specified number of days added or subtracted
+
+## Basic Examples
+
+### Adding and Subtracting Days
+
+```typescript
+import { addDays } from 'date-and-time';
+
+const date = new Date(2024, 7, 15); // August 15, 2024
+
+// Add days
+const future = addDays(date, 10);
+console.log(future); // August 25, 2024
+
+// Subtract days
+const past = addDays(date, -5);
+console.log(past); // August 10, 2024
+```
+
+### Daylight Saving Time Aware Calculations
+
+```typescript
+import { addDays } from 'date-and-time';
+import New_York from 'date-and-time/timezones/America/New_York';
+
+// Working with specific timezones
+const nyDate = new Date('2024-03-10T05:00:00Z'); // March 10, 2024 05:00 UTC (DST transition day)
+
+// Add 30 days in New York timezone
+const futureNY = addDays(nyDate, 30, New_York);
+console.log(futureNY); // April 9, 2024 04:00 UTC (EDT, DST adjusted)
+
+// UTC calculation for comparison
+const futureUTC = addDays(nyDate, 30, 'UTC');
+console.log(futureUTC); // April 9, 2024 05:00 UTC (same time, no DST adjustment)
+```
+
+## Use Cases
+
+### Work Day Calculations
+
+```typescript
+function addBusinessDays(date: Date, businessDays: number): Date {
+  let result = new Date(date);
+  let daysToAdd = businessDays;
+  
+  while (daysToAdd > 0) {
+    result = addDays(result, 1);
+    const dayOfWeek = result.getDay();
+    
+    // Skip weekends (0 = Sunday, 6 = Saturday)
+    if (dayOfWeek !== 0 && dayOfWeek !== 6) {
+      daysToAdd--;
+    }
+  }
+  
+  return result;
+}
+
+const friday = new Date(2024, 7, 23); // August 23, 2024 (Friday)
+const nextBusinessDay = addBusinessDays(friday, 1);
+console.log(nextBusinessDay); // August 26, 2024 (Monday)
+```
+
+### Date Range Generation
+
+```typescript
+function generateDateRange(startDate: Date, endDate: Date): Date[] {
+  const dates: Date[] = [];
+  let currentDate = new Date(startDate);
+  
+  while (currentDate <= endDate) {
+    dates.push(new Date(currentDate));
+    currentDate = addDays(currentDate, 1);
+  }
+  
+  return dates;
+}
+
+const start = new Date(2024, 7, 28); // August 28, 2024
+const end = new Date(2024, 8, 3);   // September 3, 2024
+const dateRange = generateDateRange(start, end);
+console.log(dateRange);
+// [Aug 28, Aug 29, Aug 30, Aug 31, Sep 1, Sep 2, Sep 3]
+```
+
+## Immutability
+
+`addDays()` does not modify the original Date object:
+
+```typescript
+const originalDate = new Date(2024, 7, 15);
+const modifiedDate = addDays(originalDate, 10);
+
+console.log(originalDate); // August 15, 2024 (unchanged)
+console.log(modifiedDate); // August 25, 2024 (new object)
+```
+
+## See Also
+
+- [`addYears()`](./addYears) - Add/subtract years
+- [`addMonths()`](./addMonths) - Add/subtract months  
+- [`addHours()`](./addHours) - Add/subtract hours
+- [`addMinutes()`](./addMinutes) - Add/subtract minutes
+- [`addSeconds()`](./addSeconds) - Add/subtract seconds
+- [`addMilliseconds()`](./addMilliseconds) - Add/subtract milliseconds
+- [`subtract()`](./subtract) - Calculate differences with Duration objects

docs/api/addHours.md

@@ -0,0 +1,127 @@
+# addHours()
+
+Adds or subtracts hours from a Date object.
+
+## Syntax
+
+```typescript
+addHours(dateObj, hours)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `dateObj` | `Date` | Yes | The base Date object |
+| `hours` | `number` | Yes | Number of hours to add (positive) or subtract (negative) |
+
+### Returns
+
+`Date` - A new Date object with the specified number of hours added or subtracted
+
+## Basic Examples
+
+### Adding and Subtracting Hours
+
+```typescript
+import { addHours } from 'date-and-time';
+
+const date = new Date(2024, 7, 15, 14, 30, 45); // August 15, 2024 14:30:45
+
+// Add hours
+const future = addHours(date, 6);
+console.log(future);  // August 15, 2024 20:30:45
+
+// Subtract hours
+const past = addHours(date, -3);
+console.log(past);  // August 15, 2024 11:30:45
+```
+
+## Use Cases
+
+### Work Hours Calculation
+
+```typescript
+function addWorkingHours(startDate: Date, workHours: number): Date {
+  // Assuming 8-hour work days, 5 days a week
+  const hoursPerDay = 8;
+  const result = new Date(startDate);
+  let remainingHours = workHours;
+  
+  while (remainingHours > 0) {
+    const dayOfWeek = result.getDay();
+    
+    // Skip weekends
+    if (dayOfWeek === 0 || dayOfWeek === 6) {
+      result.setDate(result.getDate() + 1);
+      continue;
+    }
+    
+    const hoursToAdd = Math.min(remainingHours, hoursPerDay);
+    const newTime = addHours(result, hoursToAdd);
+    result.setTime(newTime.getTime());
+    remainingHours -= hoursToAdd;
+    
+    if (remainingHours > 0) {
+      // Move to next day, reset to start of work day
+      result.setDate(result.getDate() + 1);
+      result.setHours(9, 0, 0, 0); // 9 AM start
+    }
+  }
+  
+  return result;
+}
+
+const projectStart = new Date(2024, 7, 15, 9, 0); // August 15, 2024 09:00
+const completion = addWorkingHours(projectStart, 24); // 24 working hours
+console.log(completion);
+```
+
+### Shift Scheduling
+
+```typescript
+function generateShiftSchedule(startDate: Date, shiftHours: number, numberOfShifts: number): Date[] {
+  const shifts: Date[] = [];
+  let currentStart = new Date(startDate);  
+
+  for (let i = 0; i < numberOfShifts; i++) {
+    shifts.push(new Date(currentStart));
+    currentStart = addHours(currentStart, shiftHours);
+  }
+  
+  return shifts;
+}
+
+const firstShift = new Date(2024, 7, 15, 6, 0); // August 15, 2024 06:00
+const schedule = generateShiftSchedule(firstShift, 8, 5); // 5 shifts of 8 hours each
+console.log(schedule);
+// [
+//   August 15, 2024 06:00,  // Shift 1
+//   August 15, 2024 14:00,  // Shift 2  
+//   August 15, 2024 22:00,  // Shift 3
+//   August 16, 2024 06:00,  // Shift 4
+//   August 16, 2024 14:00   // Shift 5
+// ]
+```
+
+## Immutability
+
+`addHours()` does not modify the original Date object:
+
+```typescript
+const originalDate = new Date(2024, 7, 15, 14, 30);
+const modifiedDate = addHours(originalDate, 5);
+
+console.log(originalDate); // August 15, 2024 14:30:00 (unchanged)
+console.log(modifiedDate); // August 15, 2024 19:30:00 (new object)
+```
+
+## See Also
+
+- [`addYears()`](./addYears) - Add/subtract years
+- [`addMonths()`](./addMonths) - Add/subtract months
+- [`addDays()`](./addDays) - Add/subtract days
+- [`addMinutes()`](./addMinutes) - Add/subtract minutes
+- [`addSeconds()`](./addSeconds) - Add/subtract seconds
+- [`addMilliseconds()`](./addMilliseconds) - Add/subtract milliseconds
+- [`subtract()`](./subtract) - Calculate differences with Duration objects

docs/api/addMilliseconds.md

@@ -0,0 +1,124 @@
+# addMilliseconds()
+
+Adds or subtracts milliseconds from a Date object.
+
+## Syntax
+
+```typescript
+addMilliseconds(dateObj, milliseconds)
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `dateObj` | `Date` | Yes | The base Date object |
+| `milliseconds` | `number` | Yes | Number of milliseconds to add (positive) or subtract (negative) |
+
+### Returns
+
+`Date` - A new Date object with the specified number of milliseconds added or subtracted
+
+## Basic Examples
+
+### Adding and Subtracting Milliseconds
+
+```typescript
+import { addMilliseconds } from 'date-and-time';
+
+const date = new Date(2024, 7, 15, 14, 30, 45, 123);  // August 15, 2024 14:30:45.123
+
+// Add milliseconds
+const future = addMilliseconds(date, 500);
+console.log(future);  // August 15, 2024 14:30:45.623
+
+// Subtract milliseconds
+const past = addMilliseconds(date, -200);
+console.log(past);  // August 15, 2024 14:30:44.923
+```
+
+## Use Cases
+
+### High-Precision Timing
+
+```typescript
+class PrecisionTimer {
+  private startTime: Date
+  
+  start(): void {
+    this.startTime = new Date();
+  }
+  
+  elapsedMs(): number {
+    if (!this.startTime) {
+      return 0;
+    }
+    return Date.now() - this.startTime.getTime();
+  }
+  
+  addPreciseDelay(baseTime: Date, delayMs: number): Date {
+    return addMilliseconds(baseTime, delayMs);
+  }
+  
+  scheduleNextExecution(intervalMs: number): Date {
+    return addMilliseconds(new Date(), intervalMs);
+  }
+}
+
+const timer = new PrecisionTimer();
+
+timer.start();
+// ... perform operations ...
+console.log(`Operation took: ${timer.elapsedMs()}ms`);
+
+const nextRun = timer.scheduleNextExecution(150); // Schedule 150ms from now
+console.log(`Next execution at: ${nextRun.toISOString()}`);
+```
+
+### Animation Frame Scheduling
+
+```typescript
+function createAnimationSchedule(startTime: Date, frameRate: number, duration: number) {
+  const frameInterval = 1000 / frameRate; // ms per frame
+  const totalFrames = Math.floor((duration * 1000) / frameInterval);
+  const schedule: { frame: number, time: Date }[] = [];  
+
+  for (let frame = 0; frame < totalFrames; frame++) {
+    const frameTime = addMilliseconds(startTime, frame * frameInterval);
+    schedule.push({ frame, time: frameTime });
+  }
+  
+  return schedule;
+}
+
+const animationStart = new Date();  // Animation starts now
+const frames = createAnimationSchedule(animationStart, 60, 2);  // 60 FPS for 2 seconds
+
+console.log(`Animation has ${frames.length} frames`);
+console.log('First 5 frames:');
+frames.slice(0, 5).forEach(f => {
+  console.log(`Frame ${f.frame}: ${f.time.toISOString()}`);
+});
+```
+
+## Immutability
+
+`addMilliseconds()` does not modify the original Date object:
+
+```typescript
+const originalDate = new Date(2024, 7, 15, 14, 30, 45, 123);
+const modifiedDate = addMilliseconds(originalDate, 500);
+
+console.log(originalDate);  // August 15, 2024 14:30:45.123 (unchanged)
+console.log(modifiedDate);  // August 15, 2024 14:30:45.623 (new object)
+```
+
+## See Also
+
+- [`addYears()`](./addYears) - Add/subtract years
+- [`addMonths()`](./addMonths) - Add/subtract months
+- [`addDays()`](./addDays) - Add/subtract days
+- [`addHours()`](./addHours) - Add/subtract hours
+- [`addMinutes()`](./addMinutes) - Add/subtract minutes
+- [`addSeconds()`](./addSeconds) - Add/subtract seconds
+- [`subtract()`](./subtract) - Calculate differences with Duration objects