feat(generator): support doc comments for schema descriptions #61
Conversation
Add support for using Dart doc comments (///) as a source for schema
descriptions, with annotation-based descriptions taking precedence
as overrides.
This allows developers to use standard Dart documentation comments
instead of explicitly setting description in annotations:
```dart
/// User profile with comprehensive field descriptions
@AckModel()
class UserProfile {
/// Unique identifier for the user
final String id;
/// User's full display name
@minlength(2)
final String name;
}
```
Priority order:
1. @AckField(description: '...') / @AckModel(description: '...')
2. Dart doc comments (/// ...)
3. No description
Features:
- Parse single-line doc comments (/// ...)
- Parse multi-line doc comments (joined with spaces)
- Parse block doc comments (/** ... */)
- Annotation descriptions override doc comments
- Full backwards compatibility with existing code
…nt tests
- Extract _parseDocComment as static method in FieldAnalyzer for reuse
- Remove duplicate implementation from ModelAnalyzer (42 lines)
- Fix edge case: change contains('///') to startsWith('///') for stricter matching
- Add 3 new tests for block comment (/** */) parsing
|
To view this pull requests documentation preview, visit the following URL: Documentation is deployed and generated using docs.page. |
Move parseDocComment from FieldAnalyzer static method to top-level function in lib/src/utils/doc_comment_utils.dart, following the ack package utility conventions. - Create new utils/ directory with doc_comment_utils.dart - Remove static method from FieldAnalyzer - Update ModelAnalyzer to use direct function import - Reduces coupling between analyzer classes
Update generated file to include doc comment descriptions from the schema doc comments feature.
There was a problem hiding this comment.
Pull request overview
This PR adds support for automatically extracting documentation from Dart doc comments (/// and /** */) to populate schema descriptions in the generated code. Explicit annotations in @AckModel and @AckField take precedence over doc comments, which serve as a fallback. The implementation includes a new utility module for parsing doc comments and comprehensive test coverage.
Changes:
- Added a new utility module (
doc_comment_utils.dart) with a reusable function for parsing Dart documentation comments - Updated
ModelAnalyzerandFieldAnalyzerto fall back to doc comments when explicit description annotations are not provided - Added comprehensive test coverage for both
///and/** */comment styles, including multi-line comments, special characters, and annotation override behavior
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/ack_generator/lib/src/utils/doc_comment_utils.dart | New utility module providing the parseDocComment function to parse both /// and /** */ style documentation comments |
| packages/ack_generator/lib/src/analyzer/model_analyzer.dart | Updated to use doc comments as fallback for class descriptions when no explicit annotation is provided |
| packages/ack_generator/lib/src/analyzer/field_analyzer.dart | Updated to use doc comments as fallback for field descriptions when no explicit annotation is provided |
| packages/ack_generator/test/description_generation_test.dart | Added comprehensive test coverage for doc comment extraction including single-line, multi-line, block comments, and annotation override behavior |
| example/lib/test_extension_types.g.dart | Regenerated example output showing doc comment descriptions being properly extracted and included in generated schemas |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| /// final description = parseDocComment('/// User name field'); | ||
| /// // Returns: 'User name field' | ||
| /// ``` | ||
| String? parseDocComment(String? docComment) { |
There was a problem hiding this comment.
The parseDocComment function lacks direct unit tests. While integration tests cover its usage through the generator, consider adding dedicated unit tests for this utility function to cover edge cases such as empty comments, comments with only whitespace, mixed comment styles, and malformed comments. This would make the function more maintainable and easier to debug.
| final docComment = field.documentationComment; | ||
| if (docComment != null && docComment.isNotEmpty) { | ||
| return parseDocComment(docComment); |
There was a problem hiding this comment.
The check docComment.isNotEmpty is redundant since parseDocComment already handles null and empty strings. This check can be simplified to just if (docComment != null) to reduce duplication and rely on the utility function's validation logic.
Remove redundant null/empty checks since parseDocComment already handles these cases internally.
Add support for Dart doc comments as schema descriptions in the code generator. Documentation comments (/// and /** */) can now be automatically used to populate schema descriptions, with explicit annotations taking precedence. Includes comprehensive test coverage for both comment styles, multi-line comments, and the annotation override behavior. Refactored shared comment parsing logic into a reusable static method. All tests passing.