Repository navigation
Conversation
Reviewer's GuideAPIExtend the analyzer and generator interfaces to support core-only discovery, optional samples, and a core-only index document.
Uses of the APIWire the new core-only mode into generation, including source discovery, service and category discovery, collision checks, and output generation.
Discover plain-C# components and core service-related types, and adapt analyzer paths and sample lookup for core-only generation.
ConfigurationMake the root option optional so core-only mode can locate the core project from the current working directory while preserving validation of explicit empty values.
DocumentationUpdate English and Chinese usage guidance to explain core-only discovery, invocation, and verification.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Linked issuesChecked at commit cbebff7 #1302 feat(LLMsDocsGenerator): generate documentation based on components · 1 of 1 met
|
There was a problem hiding this comment.
Hey - I've found 5 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="126" />
<code_context>
Directory.CreateDirectory(_outputPath);
var indexPath = Path.Combine(_outputPath, "llms.txt");
- await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh"));
+ await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh", coreOnly));
Logger($"Generated: {indexPath}");
</code_context>
<issue_to_address>
**Index and documents become inconsistent**
When generation fails or is interrupted after writing the index but before all document writes and stale-file cleanup finish, `GenerateAllAsync` writes the index before component and service files, so an I/O failure or interruption leaves the index paired with incomplete or stale documents, and consumers see missing or outdated documentation.
Write and clean up a complete staged output, then publish it only after all operations succeed.
</issue_to_address>
### Comment 2
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="126" />
<code_context>
Directory.CreateDirectory(_outputPath);
var indexPath = Path.Combine(_outputPath, "llms.txt");
- await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh"));
+ await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh", coreOnly));
Logger($"Generated: {indexPath}");
</code_context>
<issue_to_address>
**Concurrent runs leave broken links**
When two core-only invocations target the same output directory while analyzing different source snapshots, two generators targeting the same output can interleave writes and stale-file cleanup: one run can delete a component file the other run’s index references, leaving missing documentation in the final output. No per-output serialization or isolated publish step prevents this.
Serialize generation per output directory or publish each complete run from an isolated staging directory.
</issue_to_address>
### Comment 3
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs" line_range="68-83" />
<code_context>
}
- var configuredPackages = coreOnly ? new List<ExtensionPackage>() : provider.ParseExtensions();
+ if (coreOnly)
+ {
+ var duplicateComponent = components.GroupBy(component => component.Name, StringComparer.OrdinalIgnoreCase)
+ .FirstOrDefault(group => group.Skip(1).Any());
+ if (duplicateComponent != null)
+ {
+ throw new InvalidDataException($"Core component names collide: {duplicateComponent.Key}");
+ }
+
+ var componentNames = components.Select(component => component.Name).ToHashSet(StringComparer.OrdinalIgnoreCase);
</code_context>
<issue_to_address>
**Default docs overwrite name collisions**
When default-mode analysis finds distinct component or service types with the same simple name, the duplicate-name checks run only in core-only mode, so default generation writes each component and service to `components/{Name}.txt` without checking collisions. Two different types with the same simple name overwrite one another, and index links resolve to the last-written file.
Validate duplicate output filenames in both modes before writing documentation.
</issue_to_address>
### Comment 4
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs" line_range="116" />
<code_context>
+ var model = _compilation.GetSemanticModel(declaration.SyntaxTree);
+ if (model.GetDeclaredSymbol(declaration) is not INamedTypeSymbol symbol ||
+ symbol.DeclaredAccessibility != Accessibility.Public || symbol.ContainingType != null ||
+ seenTypes.Contains(symbol.ToDisplayString(FullNameFormat)) || !IsComponentType(symbol))
+ {
+ continue;
</code_context>
<issue_to_address>
**Abstract bases appear as components**
When a public abstract class in a plain `.cs` file inherits `ComponentBase` or `IComponent` and has parameters, `AnalyzeAllComponentsAsync` accepts public abstract classes when `IsComponentType` succeeds; `BuildComponentInfo` collects their inherited parameters, so they are added to the component index and get documentation links even though they cannot be used as components.
Exclude abstract types from this component-discovery pass, unless abstract component bases are intentionally meant to appear as components.
</issue_to_address>
### Comment 5
<location path="tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs" line_range="256" />
<code_context>
+ symbol.DeclaringSyntaxReferences.Select(reference => reference.GetSyntax())
+ .OfType<TypeDeclarationSyntax>().SelectMany(type => type.AttributeLists)
+ .SelectMany(list => list.Attributes).Any(attribute =>
+ attribute.Name.ToString().Split('.').Last() is "Obsolete" or "ObsoleteAttribute"))
+ {
+ continue;
</code_context>
<issue_to_address>
**Obsolete services remain documented**
When a public service uses an alias for `System.ObsoleteAttribute`, `AnalyzeCoreServicesAsync` checks attribute-name text instead of the resolved attribute symbol, so it includes the obsolete service in the generated index and documentation.
Resolve each attribute and exclude services whose attribute symbol is `System.ObsoleteAttribute`.
</issue_to_address>| Directory.CreateDirectory(_outputPath); | ||
| var indexPath = Path.Combine(_outputPath, "llms.txt"); | ||
| await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh")); | ||
| await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh", coreOnly)); |
There was a problem hiding this comment.
🟡 Medium · Index and documents become inconsistent
When generation fails or is interrupted after writing the index but before all document writes and stale-file cleanup finish, GenerateAllAsync writes the index before component and service files, so an I/O failure or interruption leaves the index paired with incomplete or stale documents, and consumers see missing or outdated documentation.
Write and clean up a complete staged output, then publish it only after all operations succeed.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 126:
**Index and documents become inconsistent**
When generation fails or is interrupted after writing the index but before all document writes and stale-file cleanup finish, `GenerateAllAsync` writes the index before component and service files, so an I/O failure or interruption leaves the index paired with incomplete or stale documents, and consumers see missing or outdated documentation.
Write and clean up a complete staged output, then publish it only after all operations succeed.| Directory.CreateDirectory(_outputPath); | ||
| var indexPath = Path.Combine(_outputPath, "llms.txt"); | ||
| await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh")); | ||
| await File.WriteAllTextAsync(indexPath, MarkdownBuilder.BuildIndexDoc(components, categories, services, extComponents, extServices, extPackages, "zh", coreOnly)); |
There was a problem hiding this comment.
🟡 Medium · Concurrent runs leave broken links
When two core-only invocations target the same output directory while analyzing different source snapshots, two generators targeting the same output can interleave writes and stale-file cleanup: one run can delete a component file the other run’s index references, leaving missing documentation in the final output. No per-output serialization or isolated publish step prevents this.
Serialize generation per output directory or publish each complete run from an isolated staging directory.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at line 126:
**Concurrent runs leave broken links**
When two core-only invocations target the same output directory while analyzing different source snapshots, two generators targeting the same output can interleave writes and stale-file cleanup: one run can delete a component file the other run’s index references, leaving missing documentation in the final output. No per-output serialization or isolated publish step prevents this.
Serialize generation per output directory or publish each complete run from an isolated staging directory.| if (coreOnly) | ||
| { | ||
| var duplicateComponent = components.GroupBy(component => component.Name, StringComparer.OrdinalIgnoreCase) | ||
| .FirstOrDefault(group => group.Skip(1).Any()); | ||
| if (duplicateComponent != null) | ||
| { | ||
| throw new InvalidDataException($"Core component names collide: {duplicateComponent.Key}"); | ||
| } | ||
|
|
||
| var componentNames = components.Select(component => component.Name).ToHashSet(StringComparer.OrdinalIgnoreCase); | ||
| var duplicate = services.FirstOrDefault(service => componentNames.Contains(service.Name)); | ||
| if (duplicate != null) | ||
| { | ||
| throw new InvalidDataException($"Core component and service names collide: {duplicate.Name}"); | ||
| } | ||
| } |
There was a problem hiding this comment.
🟡 Medium · Default docs overwrite name collisions
When default-mode analysis finds distinct component or service types with the same simple name, the duplicate-name checks run only in core-only mode, so default generation writes each component and service to components/{Name}.txt without checking collisions. Two different types with the same simple name overwrite one another, and index links resolve to the last-written file.
Validate duplicate output filenames in both modes before writing documentation.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/DocsGenerator.cs` at lines 68-83:
**Default docs overwrite name collisions**
When default-mode analysis finds distinct component or service types with the same simple name, the duplicate-name checks run only in core-only mode, so default generation writes each component and service to `components/{Name}.txt` without checking collisions. Two different types with the same simple name overwrite one another, and index links resolve to the last-written file.
Validate duplicate output filenames in both modes before writing documentation.| var model = _compilation.GetSemanticModel(declaration.SyntaxTree); | ||
| if (model.GetDeclaredSymbol(declaration) is not INamedTypeSymbol symbol || | ||
| symbol.DeclaredAccessibility != Accessibility.Public || symbol.ContainingType != null || | ||
| seenTypes.Contains(symbol.ToDisplayString(FullNameFormat)) || !IsComponentType(symbol)) |
There was a problem hiding this comment.
🟡 Medium · Abstract bases appear as components
When a public abstract class in a plain .cs file inherits ComponentBase or IComponent and has parameters, AnalyzeAllComponentsAsync accepts public abstract classes when IsComponentType succeeds; BuildComponentInfo collects their inherited parameters, so they are added to the component index and get documentation links even though they cannot be used as components.
Exclude abstract types from this component-discovery pass, unless abstract component bases are intentionally meant to appear as components.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs` at line 116:
**Abstract bases appear as components**
When a public abstract class in a plain `.cs` file inherits `ComponentBase` or `IComponent` and has parameters, `AnalyzeAllComponentsAsync` accepts public abstract classes when `IsComponentType` succeeds; `BuildComponentInfo` collects their inherited parameters, so they are added to the component index and get documentation links even though they cannot be used as components.
Exclude abstract types from this component-discovery pass, unless abstract component bases are intentionally meant to appear as components.| symbol.DeclaringSyntaxReferences.Select(reference => reference.GetSyntax()) | ||
| .OfType<TypeDeclarationSyntax>().SelectMany(type => type.AttributeLists) | ||
| .SelectMany(list => list.Attributes).Any(attribute => | ||
| attribute.Name.ToString().Split('.').Last() is "Obsolete" or "ObsoleteAttribute")) |
There was a problem hiding this comment.
🟡 Medium · Obsolete services remain documented
When a public service uses an alias for System.ObsoleteAttribute, AnalyzeCoreServicesAsync checks attribute-name text instead of the resolved attribute symbol, so it includes the obsolete service in the generated index and documentation.
Resolve each attribute and exclude services whose attribute symbol is System.ObsoleteAttribute.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocsGenerator/ComponentAnalyzer.cs` at line 256:
**Obsolete services remain documented**
When a public service uses an alias for `System.ObsoleteAttribute`, `AnalyzeCoreServicesAsync` checks attribute-name text instead of the resolved attribute symbol, so it includes the obsolete service in the generated index and documentation.
Resolve each attribute and exclude services whose attribute symbol is `System.ObsoleteAttribute`.
Link issues
fixes #1302
Summary By Copilot
Regression?
Risk
Verification
Packaging changes reviewed?
☑️ Self Check before Merge
Summary by Sourcery
Enable the LLM documentation generator to produce standalone core component and service documentation directly from the BootstrapBlazor source.
New Features:
Bug Fixes:
Enhancements:
Documentation:
Tests: