docs: add documentation to schemantic_builder entry point

[pavelgj]

Add library and method documentation to the schemantic_builder entry point, clarifying that it is invoked by build_runner and describing the schemaBuilder factory behavior.

[gemini-code-assist]

Code Review

This pull request adds a README.md example for the schemantic_builder package and introduces library-level and function-level documentation comments in builder.dart. The review feedback suggests improving the documentation comments in builder.dart by using a @docImport directive to import package:schemantic/schemantic.dart and referencing [Schema] instead of using code spans, which will make the type clickable in the generated documentation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

To make the Schema type clickable and properly resolved in the generated documentation, use a @docImport directive to import package:schemantic/schemantic.dart and reference it as [Schema] instead of using a code span.

/// @docImport 'package:schemantic/schemantic.dart';
///
/// The build_runner entry point for the schemantic code generator.
///
/// This library exposes the [schemaBuilder] factory referenced by
/// build.yaml. It is not intended to be imported directly in application
/// code; instead it is invoked by build_runner to generate the *.g.dart
/// part files for classes annotated with [Schema].
library;

References

1. In Dart, @DocImport directives are required to make types visible in documentation comments, even if those types are already exposed via export directives.

[gemini-code-assist]

Reference the Schema class as [Schema] instead of a code span to make it a clickable link in the documentation, now that the @docImport is available.

/// Creates the [Builder] used by build_runner to generate schemantic
/// data classes and JSON schemas.
///
/// The builder emits a shared part file (with the schemantic extension) for
/// every input library, running the schema generator over each [Schema]
/// annotated declaration. The [options] are supplied by build_runner based
/// on the configuration in build.yaml.
Builder schemaBuilder(BuilderOptions options) =>