Add JSDoc examples for server.ts public interfaces

[koistya]

Description

The public interfaces in src/server.ts (CallbackResult, ServerOptions, CallbackServer) lack comprehensive JSDoc examples. This makes it harder for developers to understand how to use these interfaces effectively.

What needs to be done

Add detailed JSDoc comments with examples for:

• CallbackResult interface - Show different response scenarios
• ServerOptions interface - Demonstrate various configuration options
• CallbackServer interface - Explain the lifecycle and usage patterns

Why this matters

Good documentation directly impacts developer experience:

• Reduces time to understand the API
• Prevents common mistakes
• Improves IDE autocomplete and tooltips
• Makes the library more approachable for newcomers

Implementation considerations

⚠️ Note: This feature requires critical thinking during implementation. Consider:

1. Real-world examples: Don't just document the obvious. Include examples of edge cases and common patterns

2. Alternative approach: Consider generating documentation from tests instead of static JSDoc. This ensures examples always work.

3. Interactive documentation: Should we create a documentation site with live examples using tools like Docusaurus or TypeDoc?

4. Consistency: Establish a documentation style guide for the entire project, not just these interfaces

Current state

/**
 * Result object returned from OAuth callback containing authorization code or error details
 */
export interface CallbackResult {
  /** Authorization code returned by OAuth provider */
  code?: string;
  // ... more fields
}

Suggested improvement

/**
 * Result object returned from OAuth callback containing authorization code or error details
 * 
 * @example
 * // Successful authorization
 * const result: CallbackResult = {
 *   code: "abc123xyz",
 *   state: "random-state-123"
 * };
 * 
 * @example
 * // User denied access
 * const errorResult: CallbackResult = {
 *   error: "access_denied",
 *   error_description: "User denied access to the application",
 *   state: "random-state-123"
 * };
 * 
 * @example
 * // Invalid scope requested
 * const scopeError: CallbackResult = {
 *   error: "invalid_scope",
 *   error_description: "The requested scope is invalid, unknown, or malformed",
 *   error_uri: "https://oauth.provider.com/docs/errors#invalid_scope"
 * };
 */
export interface CallbackResult {
  // ... interface definition
}

Additional documentation needs

• Add examples for different OAuth providers (GitHub, Google, Microsoft)
• Document common error scenarios and how to handle them
• Explain the relationship between these interfaces
• Add links to relevant OAuth RFCs

Skills required

• TypeScript
• JSDoc syntax
• Technical writing
• OAuth 2.0 knowledge

Difficulty

Easy - Great for someone who wants to contribute without deep code changes