json schema: Add enum value descriptions

[AndrewNolte]

No description provided.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a significant enhancement to the rfl library by enabling the inclusion of descriptions for enum values, primarily to enrich generated JSON schemas. It provides a flexible configuration mechanism for users to define these descriptions and integrates this new capability into the schema generation processes for JSON, Avro, and Cap'n Proto. This change aims to produce more informative and developer-friendly schemas, particularly for JSON, without impacting the core serialization/deserialization functionality.

Highlights

• New enum_descriptions Configuration: Introduced a new rfl::config::enum_descriptions template to allow users to associate descriptive strings with individual enum values, enhancing schema clarity.
• Enhanced JSON Schema Generation: Updated the JSON schema generation to represent enums with descriptions using a oneOf construct, where each enum value is a StringConst with an attached description annotation.
• Internal DescribedLiteral Type: Added a new internal Type::DescribedLiteral struct within rfl::parsing::schema::Type to internally handle enum values that carry descriptions.
• Cross-Format Schema Support: Extended Avro and Cap'n Proto schema generation to recognize and process the new DescribedLiteral type, converting them to their respective enum or literal representations.
• Comprehensive Test Coverage: Included a new test file, test_enum_descriptions.cpp, to thoroughly validate the correct generation of JSON schemas for described enums and confirm that serialization/deserialization remains functional.

Changelog

• include/rfl/config.hpp
  • Added #include <string_view>.
  • Introduced rfl::config::enum_descriptions template for associating descriptions with enum values.
• include/rfl/json/schema/Type.hpp
  • Added StringConst struct to represent string constants with annotations.
  • Included StringConst in the ReflectionType variant.
• include/rfl/parsing/Parser_enum.hpp
  • Included ../config.hpp.
  • Implemented logic to generate Type::DescribedLiteral for enums that have descriptions defined via rfl::config::enum_descriptions.
• include/rfl/parsing/schema/Type.hpp
  • Reordered include directives.
  • Defined DescribedLiteral struct, including an inner ValueWithDescription struct.
  • Added DescribedLiteral to the VariantType.
• src/rfl/avro/to_schema.cpp
  • Added handling for Type::DescribedLiteral to convert it into an Avro enum schema, extracting symbols from described values.
• src/rfl/capnproto/to_schema.cpp
  • Added handling for Type::DescribedLiteral to convert it into a Cap'n Proto literal schema, extracting values from described literals.
• src/rfl/json/to_schema.cpp
  • Adjusted formatting for is_same_v checks within is_optional function.
  • Implemented conversion of Type::DescribedLiteral to a JSON schema oneOf structure, using StringConst with descriptions for each enum value.
• tests/json/test_enum_descriptions.cpp
  • Added a new test file.
  • Included tests to verify that JSON schema generation correctly produces oneOf with const and description for enums with descriptions.
  • Included tests to confirm that standard enums without descriptions still generate as simple enum arrays.
  • Added tests to ensure that read and write operations for structs containing described enums function as expected.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a valuable feature allowing users to add descriptions to enum values, which are then incorporated into the generated JSON schema. The implementation correctly defines a new configuration struct rfl::config::enum_descriptions for users to specialize, and integrates this into the schema generation process across JSON, Avro, and Cap'n Proto. For JSON schema, described enums are appropriately translated into a oneOf structure with const and description annotations, enhancing the clarity and usability of the generated schemas. The changes also include necessary updates to internal schema types and a comprehensive test suite that verifies both the schema generation and the continued functionality of serialization/deserialization. The approach is well-designed and robust.