docs: add comprehensive JSDoc documentation to WatcherOptions type

[NotYoojun]

This PR enhances the TypeScript developer experience by adding comprehensive JSDoc documentation to the WatcherOptions type definition. Each option now includes detailed descriptions, use cases, and default values, making the API more discoverable and easier to use without constantly referring to external documentation.

Changes

1. Added JSDoc comments to all WatcherOptions properties with:
   • Clear descriptions of what each option does
   • Practical usage guidance and performance implications
   • Default values for each option (using @default tags)
   • Important behavioral notes (e.g., when options are ignored)
   • Cross-references to related options where applicable
2. Added a type-level documentation comment linking to the official options documentation

Benefits

1. Better IDE Support: IntelliSense and auto-completion will now show helpful descriptions for each option
2. Reduced Context Switching: Developers can understand options without leaving their code editor
3. Improved Discoverability: Default values and usage guidance help users make informed decisions
4. TypeScript-First Documentation: Aligns with the library's TypeScript-ready positioning mentioned in the README