Improve parser library performance and documentation

[Copilot]

This PR enhances the parser library's performance and documentation by implementing adapter caching and comprehensive KDoc improvements.

Performance Improvements

Problem: The parser was creating new JsonAdapter instances on every method call, causing unnecessary reflection overhead when parsing multiple files.

Solution: Implemented lazy-initialized cached adapters that are reused across parsing calls:

// Before: Created new adapter each time
fun parseRecords(json: String): Records {
  val adapter: JsonAdapter<Records> = moshi.adapter(Records::class.java)
  return adapter.fromJson(json)!!
}

// After: Uses cached adapter
private val recordsAdapter: JsonAdapter<Records> by lazy { moshi.adapter(Records::class.java) }

fun parseRecords(json: String): Records {
  return recordsAdapter.fromJson(json)!!
}

Impact: Significantly reduces parsing time for repeated calls, especially beneficial when processing multiple JSON files with the same Parser instance.

Documentation Enhancements

Enhanced KDoc with comprehensive implementation details:

• Performance characteristics: Thread-safety, memory efficiency, adapter caching behavior
• Usage recommendations: Parser instance reuse, BufferedSource preference for large files
• Exception handling: Detailed @throws documentation for JsonDataException and NullPointerException
• Parameter documentation: Added @param and @return annotations for all public methods
• Code examples: Updated examples to demonstrate efficient usage patterns

Testing

Added ParserPerformanceTest to validate the performance improvements and ensure adapter caching works correctly across different JSON types.

Backward Compatibility

All changes are fully backward compatible - existing code using the parser will continue to work unchanged while automatically benefiting from the performance improvements.

Fixes #123.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[hossain-khan]

Will take care of this being here later.