Json Schema: Add enum value descriptions

[AndrewNolte]

No description provided.

[gemini-code-assist]

Summary of Changes

Hello @AndrewNolte, 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 enhances the rfl library's JSON schema generation capabilities by enabling the inclusion of descriptions for individual enum values. This allows developers to provide richer metadata for their enums, which translates into more informative and self-documenting JSON schemas, improving clarity for API consumers. The changes introduce a new configuration mechanism for defining these descriptions and update the schema generation logic to correctly represent them.

Highlights

• Enum Description Configuration: Introduced a new rfl::config::enum_descriptions template to allow users to specify descriptions for individual enum values, enhancing schema documentation.
• JSON Schema Generation Enhancement: Modified the JSON schema generation process to incorporate these enum descriptions, producing oneOf schemas with const and description fields for described enum values.
• New Internal Schema Types: Added new internal schema types, StringConst and DescribedLiteral, to support the representation of described enum values within the schema structure.
• Comprehensive Testing: Included a comprehensive test suite to validate the correct generation of JSON schemas with enum descriptions and ensure existing read/write functionality remains intact.

Changelog

• include/rfl/config.hpp
  • Included <string_view> for string manipulation.
  • Defined the rfl::config::enum_descriptions template to allow specialization for providing enum value descriptions.
• include/rfl/json/schema/Type.hpp
  • Added a new StringConst struct to represent a string constant with an optional description.
  • Integrated StringConst into the ReflectionType variant to support described string constants.
• include/rfl/parsing/Parser_enum.hpp
  • Included ../config.hpp to access the new enum description configuration.
  • Modified the Parser logic to generate Type::DescribedLiteral for enums that have enum_descriptions specialized, allowing descriptions to be carried through the parsing process.
• include/rfl/parsing/schema/Type.hpp
  • Defined a new DescribedLiteral struct, including a nested ValueWithDescription struct, to represent literals that have associated descriptions.
  • Added DescribedLiteral to the VariantType variant, enabling its use in the internal schema representation.
• src/rfl/json/to_schema.cpp
  • Implemented a constexpr if branch within type_to_json_schema_type to specifically handle Type::DescribedLiteral.
  • Converted Type::DescribedLiteral into a schema::Type::OneOf containing schema::Type::StringConst for each described value, aligning with JSON Schema best practices for described enum values.
• tests/json/test_enum_descriptions.cpp
  • Added a new test file to validate the enum description functionality.
  • Defined Color enum with enum_descriptions specialization and Size enum without for comparative testing.
  • Created a Config struct utilizing both described and undescribed enums.
  • Implemented test_enum_descriptions_schema to verify that the generated JSON schema correctly includes oneOf with const and description for described enums.
  • Implemented test_enum_descriptions_read_write to confirm that serialization and deserialization continue to function correctly with described enums.

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 mechanism to add descriptions to enum values for JSON schema generation. This is achieved by specializing a new rfl::config::enum_descriptions template for specific enum types. The changes are well-implemented across the configuration, parsing, and schema generation layers, and include a comprehensive set of tests. My feedback focuses on improving the example and test code to encourage more robust and maintainable user specializations by avoiding default cases in switch statements over enums.

[gemini-code-assist]

Using default in a switch over an enum can suppress useful compiler warnings if a new enumerator is added but not handled in the switch. By removing the default case and having a return statement after the switch, you encourage developers to explicitly handle all enum values. The compiler will warn them if they miss one, leading to more maintainable code.

Suggested change

	// default: return "";
	// }
	// }
	// return "";

[gemini-code-assist]

Similar to my other comment, it's better to avoid default here. This will cause the compiler to issue a warning if a new value is added to the Color enum but not handled in this switch, making the test more robust against future changes.

    }
    return "";