Improve Documentation and Test Coverage for JToon

[felipestanzani]

📦 Improve Documentation and Test Coverage for JToon

Summary

This PR enhances the JToon library with comprehensive POJO test coverage, improved documentation structure, and better developer experience for local builds.

Changes

🧪 Enhanced Test Coverage

• Added 17 new test cases covering POJO encoding scenarios
• Created dedicated TestPojos.java with test record classes for:
  • Simple POJOs with basic fields
  • Nested object structures
  • Collections (Lists and Maps)
  • Jackson annotations (@JsonProperty, @JsonIgnore)
• Tests validate proper encoding of POJOs in both standalone and tabular formats
• All tests organized in nested JUnit 5 test classes for better readability

📚 Documentation Improvements

• Extracted TOON specification into dedicated TOON-SPECIFICATION.md (743 lines)
  • Complete format rules and canonical formatting guidelines
  • Detailed benchmarks and accuracy measurements
  • Comprehensive quoting rules and examples
  • LLM usage recommendations
• Streamlined README.md (reduced by ~450 lines)
  • Focused on quick start and practical usage
  • All code examples now use Java records instead of verbose Map constructions
  • Cleaner, more modern examples that better represent typical Java usage
  • Links to full specification for detailed information

🔧 Developer Experience

• Modified build.gradle to enforce Java 21 toolchain only in CI environments
• Local developers can now use their installed JDK version
• Improves local development workflow while maintaining CI build consistency

Examples of Updated Code Style

Before (verbose Map construction):

Map<String, Object> user = new LinkedHashMap<>();
user.put("id", 123);
user.put("name", "Ada");
user.put("tags", List.of("reading", "gaming"));

After (clean records):

record User(int id, String name, List<String> tags) {}
User user = new User(123, "Ada", List.of("reading", "gaming"));

Files Changed

• build.gradle - Conditional Java toolchain enforcement
• README.md - Streamlined and modernized with record examples
• TOON-SPECIFICATION.md - New comprehensive format specification
• src/test/java/com/felipestanzani/jtoon/JToonTest.java - Added POJO test suite
• src/test/java/com/felipestanzani/jtoon/TestPojos.java - New test record classes

Testing

All existing tests pass, plus 17 new test cases added covering POJO encoding scenarios.

Breaking Changes

None. This is a non-breaking enhancement that improves documentation and test coverage.

Summary by CodeRabbit

• Documentation

  • Reorganized README with consolidated reference to new TOON Format Specification for detailed rules and examples.
  • Added comprehensive TOON-SPECIFICATION.md covering syntax, formatting rules, LLM prompt conventions, and example transformations.

• Tests

  • Expanded test coverage with comprehensive test suite for Plain Old Java Objects, nested structures, Jackson annotations, and container formats.

• Chores

  • Updated build configuration for conditional JDK toolchain enforcement.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Updates IDE to Java 25, conditionalizes build toolchain enforcement for CI environments, consolidates documentation into a new TOON specification file, and expands test coverage with record-based POJOs and new test fixtures.

Changes

Cohort / File(s)	Summary
IDE Configuration \.idea/misc\.xml	Updates ProjectRootManager languageLevel from JDK_22 to JDK_25 and adds default="true" attribute.
Documentation README\.md, TOON-SPECIFICATION\.md	README consolidated and shortened, replacing Format/Benchmark/Usage sections with reference to new comprehensive TOON-SPECIFICATION.md. Code examples updated to record-based data models. New TOON-SPECIFICATION.md document provides detailed syntax, formatting rules, and LLM integration guidance.
Build Configuration build\.gradle	Java toolchain languageVersion = 21 now conditionally applied only when CI environment variable equals "true"; local builds inherit system JDK.
Test Infrastructure src/test/java/com/felipestanzani/jtoon/TestPojos\.java	New test helper file introducing 16 public Java records (Person, Product, Address, Employee, etc.) with support for nested objects, collections, and Jackson annotations (@JsonProperty, @JsonIgnore).
Test Expansion src/test/java/com/felipestanzani/jtoon/JToonTest\.java	Adds @tag("unit") annotation to test class; imports TestPojos; extends coverage with nested POJOs test suite covering simple records, nested structures, Jackson annotations, collections, and tabular formats.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• TestPojos.java: Review 16 new record declarations for correctness of types, naming conventions, and Jackson annotation placement.
• JToonTest.java: Verify new nested test classes and test cases adequately cover POJO scenarios, nested structures, and collection handling.
• TOON-SPECIFICATION.md: Skim comprehensively for consistency with implementation and examples; cross-reference with README updates.
• build.gradle: Validate CI environment conditional logic and confirm default behavior for local development.

Possibly related PRs

• Enhance build configuration for Maven publishing and signing; update … #1: Modifies build.gradle Java toolchain and Maven publishing configuration; related through build toolchain management and CI/local development coordination.

Poem

🐰 Records and specs now mark the way,
Tests grow robust with each new day,
Java's climbing, twenty-five's the call,
TOON-ification conquers all! 🎯

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch code_coverage

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2403ab3 and 8063b37.

📒 Files selected for processing (6)

• .idea/misc.xml (1 hunks)
• README.md (8 hunks)
• TOON-SPECIFICATION.md (1 hunks)
• build.gradle (1 hunks)
• src/test/java/com/felipestanzani/jtoon/JToonTest.java (3 hunks)
• src/test/java/com/felipestanzani/jtoon/TestPojos.java (1 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}