From 53155cceddb8fbbece9b31afbed7b0593325305d Mon Sep 17 00:00:00 2001 From: naipaka Date: Sun, 8 Dec 2024 20:17:52 +0900 Subject: [PATCH 1/4] feat: Add assists for macro documentation comments --- .vscode/settings.json | 1 + packages/altive_lints/lib/altive_lints.dart | 10 +++ .../assists/add_macro_document_comments.dart | 88 +++++++++++++++++++ .../add_macro_template_document_comment.dart | 80 +++++++++++++++++ ..._with_macro_template_document_comment.dart | 85 ++++++++++++++++++ 5 files changed, 264 insertions(+) create mode 100644 packages/altive_lints/lib/src/assists/add_macro_document_comments.dart create mode 100644 packages/altive_lints/lib/src/assists/add_macro_template_document_comment.dart create mode 100644 packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart diff --git a/.vscode/settings.json b/.vscode/settings.json index 67ac775..849591d 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -6,6 +6,7 @@ "bools", "combinators", "diffscrape", + "endtemplate", "gocolly", "interps", "ints", diff --git a/packages/altive_lints/lib/altive_lints.dart b/packages/altive_lints/lib/altive_lints.dart index 3eb31a4..e8591d9 100644 --- a/packages/altive_lints/lib/altive_lints.dart +++ b/packages/altive_lints/lib/altive_lints.dart @@ -1,5 +1,8 @@ import 'package:custom_lint_builder/custom_lint_builder.dart'; +import 'src/assists/add_macro_document_comments.dart'; +import 'src/assists/add_macro_template_document_comment.dart'; +import 'src/assists/wrap_with_macro_template_document_comment.dart'; import 'src/lints/avoid_consecutive_sliver_to_box_adapter.dart'; import 'src/lints/avoid_hardcoded_color.dart'; import 'src/lints/avoid_hardcoded_japanese.dart'; @@ -26,4 +29,11 @@ class _AltivePlugin extends PluginBase { const PreferSpaceBetweenElements(), const PreferToIncludeSliverInName(), ]; + + @override + List getAssists() => [ + AddMacroDocumentComment(), + AddMacroTemplateDocumentComment(), + WrapWithMacroTemplateDocumentComment(), + ]; } diff --git a/packages/altive_lints/lib/src/assists/add_macro_document_comments.dart b/packages/altive_lints/lib/src/assists/add_macro_document_comments.dart new file mode 100644 index 0000000..8b456a4 --- /dev/null +++ b/packages/altive_lints/lib/src/assists/add_macro_document_comments.dart @@ -0,0 +1,88 @@ +import 'package:analyzer/dart/ast/ast.dart'; +import 'package:analyzer/source/source_range.dart'; +import 'package:custom_lint_builder/custom_lint_builder.dart'; + +/// {@template altive_lints.AddMacroDocumentComment} +/// An assist to add macro template documentation comments to function +/// or constructor declarations. +/// +/// This assist helps maintain consistent documentation across +/// the entire codebase by adding macro template comments +/// to each function or constructor. These comments can be used +/// for documentation generation or by other tools. +/// +/// Macro template comments follow this format: +/// +/// ```dart +/// /// {[@]macro packageName.functionName} +/// ``` +/// +/// Example: +/// +/// Before: +/// ```dart +/// void myFunction() { +/// // Function implementation +/// } +/// ``` +/// +/// After applying the assist: +/// ```dart +/// /// {[@]macro my_package.myFunction} +/// void myFunction() { +/// // Function implementation +/// } +/// ``` +/// +/// {@endtemplate} +class AddMacroDocumentComment extends DartAssist { + /// {@macro altive_lints.AddMacroDocumentComment} + AddMacroDocumentComment(); + + @override + void run( + CustomLintResolver resolver, + ChangeReporter reporter, + CustomLintContext context, + SourceRange target, + ) { + context.registry.addFunctionDeclaration((node) { + _processNode(node, target, reporter, context); + }); + + context.registry.addConstructorDeclaration((node) { + _processNode(node, target, reporter, context); + }); + } + + void _processNode( + AstNode node, + SourceRange target, + ChangeReporter reporter, + CustomLintContext context, + ) { + if (!target.intersects(node.sourceRange)) { + return; + } + + final changeBuilder = reporter.createChangeBuilder( + message: 'Add macro documentation comment', + priority: 20, + ); + + final packageName = context.pubspec.name; + var name = ''; + + if (node is FunctionDeclaration) { + name = node.name.lexeme; + } else if (node is ConstructorDeclaration) { + name = node.returnType.name; + } + + final macroComment = '/// {@macro $packageName.$name}'; + + changeBuilder.addDartFileEdit((builder) { + builder.addSimpleInsertion(node.offset, '$macroComment\n'); + }); + } +} diff --git a/packages/altive_lints/lib/src/assists/add_macro_template_document_comment.dart b/packages/altive_lints/lib/src/assists/add_macro_template_document_comment.dart new file mode 100644 index 0000000..43896f3 --- /dev/null +++ b/packages/altive_lints/lib/src/assists/add_macro_template_document_comment.dart @@ -0,0 +1,80 @@ +import 'package:analyzer/source/source_range.dart'; +import 'package:custom_lint_builder/custom_lint_builder.dart'; + +/// {@template altive_lints.AddMacroTemplateDocumentComment} +/// A Dart assist that adds a macro template documentation comment to a class +/// declaration if it does not already have one. +/// +/// This assist helps in maintaining consistent documentation across the +/// codebase by ensuring that each class has a macro template comment, which +/// can be used for generating documentation or for other tooling purposes. +/// +/// The macro template comment follows the format: +/// +/// ```dart +/// /// {[@]template packageName.className} +/// /// +/// /// {[@]endtemplate} +/// ``` +/// +/// Example usage: +/// +/// Before: +/// ```dart +/// class MyClass { +/// // Class implementation +/// } +/// ``` +/// +/// After running the assist: +/// ```dart +/// /// {[@]template my_package.MyClass} +/// /// +/// /// {[@]endtemplate} +/// class MyClass { +/// // Class implementation +/// } +/// ``` +/// +/// {@endtemplate} +class AddMacroTemplateDocumentComment extends DartAssist { + /// {@macro altive_lints.AddMacroTemplateDocumentComment} + AddMacroTemplateDocumentComment(); + + @override + void run( + CustomLintResolver resolver, + ChangeReporter reporter, + CustomLintContext context, + SourceRange target, + ) { + context.registry.addClassDeclaration((node) { + if (!target.intersects(node.sourceRange)) { + return; + } + + final docComment = node.documentationComment; + if (docComment != null) { + return; + } + + final changeBuilder = reporter.createChangeBuilder( + message: 'Add macro template documentation comment', + priority: 20, + ); + + final packageName = context.pubspec.name; + final className = node.name.lexeme; + + final template = [ + '/// {@template $packageName.$className}', + '/// ', + '/// {@endtemplate}', + ].join('\n'); + + changeBuilder.addDartFileEdit((builder) { + builder.addSimpleInsertion(node.offset, '$template\n'); + }); + }); + } +} diff --git a/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart b/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart new file mode 100644 index 0000000..1dcaa64 --- /dev/null +++ b/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart @@ -0,0 +1,85 @@ +import 'package:analyzer/dart/ast/ast.dart'; +import 'package:analyzer/source/source_range.dart'; +import 'package:custom_lint_builder/custom_lint_builder.dart'; + +/// {@template altive_lints.WrapWithMacroTemplateDocumentComment} +/// A Dart assist that wraps an existing documentation comment with a macro +/// template comment. +/// +/// This assist helps in maintaining consistent documentation across the +/// codebase by ensuring that each documentation comment is wrapped with a +/// macro template, which can be used for generating documentation or for +/// other tooling purposes. +/// +/// The macro template comment follows the format: +/// +/// ```dart +/// /// {[@]template packageName.className} +/// /// Existing documentation comment. +/// /// {[@]endtemplate} +/// ``` +/// +/// Example usage: +/// +/// Before: +/// ```dart +/// /// This is a class. +/// class MyClass { +/// // Class implementation +/// } +/// ``` +/// +/// After running the assist: +/// ```dart +/// /// {[@]template my_package.MyClass} +/// /// This is a class. +/// /// {[@]endtemplate} +/// class MyClass { +/// // Class implementation +/// } +/// ``` +/// +/// {@endtemplate} +class WrapWithMacroTemplateDocumentComment extends DartAssist { + /// {@macro altive_lints.WrapWithMacroTemplateDocumentComment} + WrapWithMacroTemplateDocumentComment(); + + @override + void run( + CustomLintResolver resolver, + ChangeReporter reporter, + CustomLintContext context, + SourceRange target, + ) { + context.registry.addComment((node) { + if (!target.intersects(node.sourceRange)) { + return; + } + + if (!node.isDocumentation) { + return; + } + + final changeBuilder = reporter.createChangeBuilder( + message: 'Wrap with macro template documentation comment', + priority: 20, + ); + + final packageName = context.pubspec.name; + final classNode = node.parent; + var className = ''; + if (classNode is ClassDeclaration) { + className = classNode.name.lexeme; + } + + final templateStart = '/// {@template $packageName.$className}'; + const templateEnd = '/// {@endtemplate}'; + + changeBuilder.addDartFileEdit((builder) { + builder + ..addSimpleInsertion(node.offset, '$templateStart\n') + ..addSimpleInsertion(node.end, '\n$templateEnd'); + }); + }); + } +} From e7dbe496d6a739063a0a0bb6f30fe45caae4e191 Mon Sep 17 00:00:00 2001 From: naipaka Date: Mon, 9 Dec 2024 09:50:03 +0900 Subject: [PATCH 2/4] doc: Update README with new macro documentation assists --- packages/altive_lints/README.md | 79 +++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/packages/altive_lints/README.md b/packages/altive_lints/README.md index 58270e4..2244de0 100644 --- a/packages/altive_lints/README.md +++ b/packages/altive_lints/README.md @@ -21,6 +21,10 @@ There are also Altive-made rules by custom_lint. - [prefer\_dedicated\_media\_query\_methods](#prefer_dedicated_media_query_methods) - [prefer\_to\_include\_sliver\_in\_name](#prefer_to_include_sliver_in_name) - [prefer\_space\_between\_elements](#prefer_space_between_elements) +- [All assists in altive\_lints](#all-assists-in-altive_lints) + - [Add macro template documentation comment](#add-macro-template-documentation-comment) + - [Add macro documentation comment](#add-macro-documentation-comment) + - [Wrap with macro template documentation comment](#wrap-with-macro-template-documentation-comment) - [Lint rules adopted by altive\_lints and why](#lint-rules-adopted-by-altive_lints-and-why) - [public\_member\_api\_docs](#public_member_api_docs) - [Migration guide](#migration-guide) @@ -318,6 +322,81 @@ class MyWidget extends StatelessWidget { } ``` +## All assists in altive_lints + +### Add macro template documentation comment + +Adds a Macros template to class declarations. +When you place the cursor on the class declaration and execute **"Add macro template documentation comment"**, the documentation is created. + +**Before:** + +```dart +class MyClass { + // Class implementation +} +``` + +**After applying the assist:** + +```dart +/// {@template my_package.MyClass} +/// +/// {@endtemplate} +class MyClass { + // Class implementation +} +``` + +### Add macro documentation comment + +Adds Macros comments to constructors and method declarations. +When you place the cursor on a constructor or method declaration and execute **"Add macro documentation comment"**, the documentation is created. + +**Before:** + +```dart +void myFunction() { + // Function implementation +} +``` + +**After applying the assist:** + +```dart +/// {@macro my_package.myFunction} +void myFunction() { + // Function implementation +} +``` + +### Wrap with macro template documentation comment + +Wraps existing documentation comments with a Macros template. +When you select the documentation comment and execute **"Wrap with macro template documentation comment"**, the documentation is created. + +**Before:** + +```dart +/// Some comment +/// More comments +class MyClass { + // Class implementation +} +``` + +**After applying the assist:** + +```dart +/// {@template my_package.MyClass} +/// Some comment +/// More comments +/// {@endtemplate} +class MyClass { + // Class implementation +} +``` + ## Lint rules adopted by altive_lints and why Reasons for adopting each lint rule. From 63261112e0fbd4f8b832fa8fcf1573a669d2f673 Mon Sep 17 00:00:00 2001 From: naipaka Date: Wed, 11 Dec 2024 09:27:11 +0900 Subject: [PATCH 3/4] feat: Prevent wrapping of existing macro template documentation comments --- .../assists/wrap_with_macro_template_document_comment.dart | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart b/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart index 1dcaa64..028af23 100644 --- a/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart +++ b/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart @@ -56,6 +56,12 @@ class WrapWithMacroTemplateDocumentComment extends DartAssist { return; } + final currentComment = node.tokens.join(); + if (currentComment.contains('{@template') && + currentComment.contains('{@endtemplate}')) { + return; + } + if (!node.isDocumentation) { return; } From a835697cc08de0a68f6d280b88c7a5d3a2b5dce9 Mon Sep 17 00:00:00 2001 From: naipaka Date: Tue, 17 Dec 2024 09:55:21 +0900 Subject: [PATCH 4/4] feat: Remove unnecessary documentation check in WrapWithMacroTemplateDocumentComment --- .../assists/wrap_with_macro_template_document_comment.dart | 4 ---- 1 file changed, 4 deletions(-) diff --git a/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart b/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart index 028af23..c71d459 100644 --- a/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart +++ b/packages/altive_lints/lib/src/assists/wrap_with_macro_template_document_comment.dart @@ -62,10 +62,6 @@ class WrapWithMacroTemplateDocumentComment extends DartAssist { return; } - if (!node.isDocumentation) { - return; - } - final changeBuilder = reporter.createChangeBuilder( message: 'Wrap with macro template documentation comment', priority: 20,