refactor: update automatic documentation generation by solid-illiaaihistov · Pull Request #315 · solid-software/solid_lints

solid-illiaaihistov · 2026-07-07T11:02:27Z

Closes #314
Closes #101

…o 101-docs-structured-parameters

…d update parameter metadata

…gration

…rove rule parsing logic

gemini-code-assist

Code Review

This pull request refactors the documentation parser for solid_lints by introducing a new DocsParser orchestrator, ParserRegexes, and a revamped ParserUtils utility class. It adds support for @docType custom types, {@template} scanning, and {@macro} expansion, while updating configuration formats to use the new plugins: solid_lints structure. Feedback on the changes highlights two issues: a potential null-pointer evaluation to 'null' when parsing fields without explicit types in ParametersParser, and a logic bug in the circular macro dependency check within ParserUtils.expandMacros that could trigger false positives on valid nested macro expansions.

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.

…rcular dependency detection logic

solid-illiaaihistov · 2026-07-07T11:11:44Z

/gemini review

gemini-code-assist

Code Review

This pull request updates the configuration structure of solid_lints to use the new plugins block, updates Docusaurus dependencies, and introduces @doctype annotations across several parameter classes. Additionally, it refactors the documentation parser utility to support custom type scanning, template/macro expansion, and MDX-safe escaping, while making lintName public across lint rules. The review feedback suggests improving error handling during documentation generation by including the field name in missing-documentation errors and passing the file path context to macro expansion errors to aid debugging.

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.

…ontext and specific field names

solid-illiaaihistov · 2026-07-07T11:35:44Z

/gemini review

gemini-code-assist

Code Review

This pull request updates the solid_lints configuration format to use the new plugins syntax, updates documentation, and significantly refactors the documentation parser to support custom types, templates, and macro expansion. Feedback on the changes includes two recommendations: first, to use uri.pathSegments.last instead of p.basenameWithoutExtension in ParserUtils.fileNameSuffix to prevent platform-dependent path parsing issues on Windows; second, to use toSource() instead of toString() on AST TypeAnnotation nodes in ParametersParser to ensure robustness across different versions of the analyzer package.

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.

…extraction logic

solid-illiaaihistov · 2026-07-07T11:44:25Z

/gemini review

gemini-code-assist · 2026-07-07T12:01:07Z

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

solid-illiaaihistov · 2026-07-07T12:05:02Z

/gemini review

gemini-code-assist · 2026-07-07T12:16:23Z

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

solid-illiaaihistov · 2026-07-08T16:21:35Z

/gemini review

gemini-code-assist · 2026-07-08T16:35:21Z

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

danylo-safonov-solid · 2026-07-09T14:34:11Z

I kinda feel like it all can be put into a single method with some helper extensions extracted:

T parse(Directory dir, {bool sortRulesAlphabetically = true}) { final files = dir .listSync(recursive: true) .whereType<File>() .where( (f) => ruleFileSuffixes.contains(ParserUtils.fileNameSuffix(f.uri)), ) .map((file) => file.path) .toList(); if (files.isEmpty) throw 'Found no rules in specified directory'; final libDir = ParserUtils.findLibDir(dir); final customTypes = { 'DiagnosticSeverity': 'String', for (final entity in libDir.listSync(recursive: true)) if (entity case File(hasDocStrings: true, :final declarations?)) for (final declaration in declarations) if (declaration case CompilationUnitMember( :final name?, :final type?, )) name: type.trim(), }; final templates = ParserUtils.scanForTemplates(libDir); final docs = [ for (final path in files) RuleParser( rulePath: path, customTypes: customTypes, templates: templates, ).parse(), ]; log('Parsed ${docs.length} rules'); return formatter.format( sortRulesAlphabetically ? docs.sortedBy((e) => e.name) : docs.toList(), ); } }

and somewhere in utils:

extension on File { bool get hasDocStrings => path.endsWith('.dart') && readAsStringSync().contains('@docType'); NodeList<CompilationUnitMember>? get declarations => tryOrNull(() => ParserUtils.parseAst(path).declarations); }

extension on CompilationUnitMember { String? get name => tryOrNull<String?>(() => ParserUtils.getDeclarationName(this)); String? get doc => documentationComment.formatted; String? get type => doc == null ? null : ParserRegexes.docTypeRegex.firstMatch(doc ?? '')?.group(1); }

T? tryOrNull<T>(T Function() f) { try { return f(); } catch (_) { return null; } }

danylo-safonov-solid · 2026-07-09T15:04:57Z

Refactored a bit:

List<ParameterDoc> parse() => File( join( ruleDirectory.path, _parametersDir, '${basename(ruleDirectory.path)}_$_parametersSuffix.dart', ), ).declarations ?.whereType<ClassDeclaration>() .map(_parseParametersDocs) .firstWhereOrNull((docs) => docs.isNotEmpty) ?? []; List<ParameterDoc> _parseParametersDocs(ClassDeclaration declaration) => [ for (final member in ParserUtils.getClassMembers( declaration, )) if (member case FieldDeclaration( isStatic: false, documentationComment: Comment(formatted: final doc), )) for (final v in member.fields.variables) if (!v.nameString.startsWith('_')) if (doc == null) throw 'Documentation is not specified for field ' '"${v.nameString}" in class: ' '${ParserUtils.getDeclarationName(declaration)}' else ParameterDoc( name: ParserUtils.camelCaseToSnakeCase(v.nameString), type: (member.fields.type?.toSource() ?? 'dynamic') .replaceAllMapped(ParserRegexes.wordRegex, (match) { final word = match.group(0)!; return customTypes[word] ?? word; }), doc: doc, ), ];

extension on VariableDeclaration { String get nameString => name.lexeme.trim(); }

danylo-safonov-solid · 2026-07-09T15:15:36Z

+  static String _cleanCommentLine(String line) {
+    if (line.startsWith('/// ')) {
+      return line.substring(4);
+    }
+    if (line.startsWith('///')) {
+      return line.substring(3);
+    }
+    return line;
+  }


Suggested change

static String _cleanCommentLine(String line) {

if (line.startsWith('/// ')) {

return line.substring(4);

}

if (line.startsWith('///')) {

return line.substring(3);

}

return line;

}

static String _trimCommentPrefix(String line) =>

line.substring(switch (line) {

_ when line.startsWith('/// ') => 4,

_ when line.startsWith('///') => 3,

_ => 0,

});

Also we can make an extension like trimChar or something

And make it:

static String _trimCommentPrefix(String line) => line.trimChar('/').trim();

danylo-safonov-solid · 2026-07-09T15:18:58Z

+  static String? formatDocumentationComment(Comment? documentationComment) {
+    if (documentationComment == null) return null;
+    return documentationComment.tokens
+        .map((token) => _cleanCommentLine(token.lexeme))
+        .join('\n')
+        .trim();
+  }


Suggested change

static String? formatDocumentationComment(Comment? documentationComment) {

if (documentationComment == null) return null;

return documentationComment.tokens

.map((token) => _cleanCommentLine(token.lexeme))

.join('\n')

.trim();

}

static String? formatDocumentationComment(Comment? documentationComment) =>

documentationComment?.tokens

.map((token) => _trimCommentPrefix(token.lexeme))

.join('\n')

.trim();

danylo-safonov-solid · 2026-07-09T15:21:20Z

+          final name = match.group(1)!;
+          final rawContent = match.group(2)!;
+          final cleanContent = rawContent
+              .split('\n')
+              .map((line) => _cleanCommentLine(line.trim()))
+              .join('\n')
+              .trim();
+
+          templates[name] = cleanContent;


I know it's in try catch, but we should also probably avoid the bang operator

Suggested change

final name = match.group(1)!;

final rawContent = match.group(2)!;

final cleanContent = rawContent

.split('\n')

.map((line) => _cleanCommentLine(line.trim()))

.join('\n')

.trim();

templates[name] = cleanContent;

final [name, rawContent] = match.groups([1, 2]);

templates[name!] = rawContent!

.split('\n')

.map((line) => _trimCommentPrefix(line.trim()))

.join('\n')

.trim();

Illia Aihistov added 5 commits July 6, 2026 16:38

feat: handle docs parser structured parameters

699a85a

Merge remote-tracking branch 'upstream/analysis_server_migration' int…

4e5f079

…o 101-docs-structured-parameters

feat: implement macro and template support in documentation parser an…

775f36f

…d update parameter metadata

docs: update documentation and examples for analysis_server_plugin mi…

fe4d39d

…gration

refactor: move and modularize documentation parsing utilities and imp…

8526b44

…rove rule parsing logic

gemini-code-assist Bot reviewed Jul 7, 2026

View reviewed changes

Comment thread lib/src/utils/docs_parser/parsers/parameters_parser.dart Outdated

Comment thread lib/src/utils/docs_parser/utils/parser_utils.dart Outdated

fix: handle null field types in parameters parser and refine macro ci…

14841eb

…rcular dependency detection logic

gemini-code-assist Bot reviewed Jul 7, 2026

View reviewed changes

Comment thread lib/src/utils/docs_parser/parsers/parameters_parser.dart

Comment thread lib/src/utils/docs_parser/utils/parser_utils.dart Outdated

Comment thread lib/src/utils/docs_parser/parsers/rule_parser.dart Outdated

refactor: enhance documentation error reporting by including source c…

b8b7b56

…ontext and specific field names

gemini-code-assist Bot reviewed Jul 7, 2026

View reviewed changes

Comment thread lib/src/utils/docs_parser/utils/parser_utils.dart Outdated

Comment thread lib/src/utils/docs_parser/parsers/parameters_parser.dart Outdated

refactor: use toSource for type parsing and improve file name suffix …

2733a66

…extraction logic

danylo-safonov-solid reviewed Jul 9, 2026

View reviewed changes

Uh oh!

Conversation

solid-illiaaihistov commented Jul 7, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

solid-illiaaihistov commented Jul 7, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

solid-illiaaihistov commented Jul 7, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

solid-illiaaihistov commented Jul 7, 2026

Uh oh!

gemini-code-assist Bot commented Jul 7, 2026

Uh oh!

solid-illiaaihistov commented Jul 7, 2026

Uh oh!

gemini-code-assist Bot commented Jul 7, 2026

Uh oh!

solid-illiaaihistov commented Jul 8, 2026

Uh oh!

gemini-code-assist Bot commented Jul 8, 2026

Uh oh!

danylo-safonov-solid Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

danylo-safonov-solid Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

danylo-safonov-solid Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

danylo-safonov-solid Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

danylo-safonov-solid Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

danylo-safonov-solid Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants