Parser fixes and documentation#348
Merged
Merged
Conversation
The `CommandLineArgsParser` no longer throws exceptions for invalid or malformed command-line arguments. Instead, errors are collected as `ParseError` objects and stored in the `CommandLineArgs.Errors` property. This ensures graceful handling of errors and defers reporting until after the application host is fully initialized. - Added `ParseError` to represent command-line argument parsing issues. - Updated `CommandLineArgs` to include a list of `Errors` and enforce `IsValid` based on their presence. - Removed direct console output and shifted error handling to a new `WriteArgErrors()` method in `AtomService`. - Adjusted tests to validate the new error collection and reporting behavior.
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request improves Atom’s CLI argument parsing/error reporting while performing a broad documentation refresh and tightening XML-doc warning enforcement by scoping CS1591 suppression to specific projects.
Changes:
- Updated CLI parsing to collect parse problems as structured
ParseErrorentries (instead of writing output / throwing during parsing), and updated runtime error reporting accordingly. - Added/expanded XML documentation across many public APIs and refreshed docs pages to align with current workflow generation (
Gen) and hosting/module patterns. - Removed global CS1591 suppression and added per-project
NoWarnwhere appropriate (tests,_atom, and generated-code-heavy modules).
Reviewed changes
Copilot reviewed 111 out of 111 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/Invex.Atom.Workflows.Tests/Invex.Atom.Workflows.Tests.csproj | Suppress CS1591 for test project. |
| tests/Invex.Atom.Tool.Tests/Invex.Atom.Tool.Tests.csproj | Suppress CS1591 for test project. |
| tests/Invex.Atom.TestUtils/Invex.Atom.TestUtils.csproj | Suppress CS1591 for test utilities project. |
| tests/Invex.Atom.Module.GithubWorkflows.Tests/Invex.Atom.Module.GithubWorkflows.Tests.csproj | Suppress CS1591 for test project. |
| tests/Invex.Atom.Module.DevopsWorkflows.Tests/Invex.Atom.Module.DevopsWorkflows.Tests.csproj | Suppress CS1591 for test project. |
| tests/Invex.Atom.Build.Tests/Invex.Atom.Build.Tests.csproj | Suppress CS1591 for test project. |
| tests/Invex.Atom.Build.Tests/ClassTests/Args/CommandLineArgsTests.cs | Add tests for parse-error behavior on CommandLineArgs. |
| tests/Invex.Atom.Build.Tests/ClassTests/Args/CommandLineArgParserTests.cs | Update tests to validate error-collecting parser behavior. |
| tests/Invex.Atom.Build.Tests/ApiSurfaceTests/PublicApiSurfaceTests.VerifyPublicApiSurface.verified.txt | Snapshot update for new public ParseError and CommandLineArgs.Errors. |
| tests/Invex.Atom.Build.SourceGenerators.Tests/Invex.Atom.Build.SourceGenerators.Tests.csproj | Suppress CS1591 for test project. |
| tests/Invex.Atom.Build.Analyzers.Tests/Invex.Atom.Build.Analyzers.Tests.csproj | Suppress CS1591 for test project. |
| src/Invex.Atom.Workflows/WorkflowOutdatedException.cs | Docs updated to reference Gen target usage. |
| src/Invex.Atom.Workflows/WorkflowLifecycleHook.cs | Error message updated to reference Gen target. |
| src/Invex.Atom.Workflows/WorkflowContext/WorkflowContext.cs | Added interface XML docs. |
| src/Invex.Atom.Workflows/WorkflowContext/IWorkflowContextProvider.cs | Added interface XML docs. |
| src/Invex.Atom.Workflows/WorkflowBuildDefinition.cs | Added XML docs describing intended inheritance/use. |
| src/Invex.Atom.Workflows/Options/WorkflowBuildOptionsExtensions.cs | Added extensive XML docs for workflow option factories. |
| src/Invex.Atom.Workflows/Options/UseCustomArtifactProvider.cs | Updated docs to use BuildOptions.Artifacts.UseCustomProvider. |
| src/Invex.Atom.Workflows/Options/TargetStepCondition.cs | Added XML docs for conditional step option. |
| src/Invex.Atom.Workflows/Options/TargetCondition.cs | Added XML docs for conditional job option. |
| src/Invex.Atom.Workflows/Options/SuppressArtifactPublishingOption.cs | Added XML docs for artifact publishing suppression. |
| src/Invex.Atom.Workflows/Options/SetupDotnetStep.cs | Added inheritdoc markers for interface members. |
| src/Invex.Atom.Workflows/Options/Injections/WorkflowParamInjectionFromEnvironment.cs | Clarified injection option docs; added env var injection record docs. |
| src/Invex.Atom.Workflows/Options/IImplicitTargetDependencyOption.cs | Added interface XML docs. |
| src/Invex.Atom.Workflows/Options/IAdditionalStepOption.cs | Added interface XML docs. |
| src/Invex.Atom.Workflows/Options/CheckoutStep.cs | Added XML docs and inheritdoc markers. |
| src/Invex.Atom.Workflows/IWorkflowBuildDefinition.cs | Added XML docs and clarified host registration behavior. |
| src/Invex.Atom.Workflows/IGen.cs | Added XML docs for Gen workflow-generation target. |
| src/Invex.Atom.Workflows/Extensions/AtomWorkflowsTextExpressionsExtensions.cs | Added XML docs for target-output expression factory. |
| src/Invex.Atom.Workflows/Experimental/WorkflowCache.cs | Added XML docs for cache utilities and options. |
| src/Invex.Atom.Workflows/Dotnet/Nuget/AddNugetFeedsStep.cs | Documented SyncAtomToolVersionToLibraryVersion and inheritdoc markers. |
| src/Invex.Atom.Workflows/Dotnet/DotnetWorkflowLabelsExtensions.cs | Added XML docs for .NET workflow label anchors. |
| src/Invex.Atom.Workflows/Definition/WorkflowTypes.cs | Added XML docs for extension anchor class. |
| src/Invex.Atom.Workflows/Definition/WorkflowTargetDefinition.cs | Documented workflow option merge semantics. |
| src/Invex.Atom.Workflows/Definition/WorkflowSteps.cs | Added XML docs for step factory anchor. |
| src/Invex.Atom.Workflows/Definition/WorkflowPresets.cs | Added XML docs for preset anchor. |
| src/Invex.Atom.Workflows/Definition/WorkflowLabels.cs | Added XML docs for label factory anchor. |
| src/Invex.Atom.Workflows/Definition/Triggers/WorkflowTriggers.cs | Added XML docs for trigger presets/factories. |
| src/Invex.Atom.Workflows/DebugWorkflow.cs | Added XML docs for debug workflow type/writer. |
| src/Invex.Atom.Tool/FileFinder.cs | Added XML docs for project file discovery logic. |
| src/Invex.Atom.Module.GitVersion/IGitVersion.cs | Added XML docs for module behavior and host wiring. |
| src/Invex.Atom.Module.GitVersion/Flags/GitVersionProvideBuildVersionFlag.cs | Added XML docs for build-option flag. |
| src/Invex.Atom.Module.GitVersion/Flags/GitVersionProvideBuildIdFlag.cs | Added XML docs for build-option flag. |
| src/Invex.Atom.Module.GitVersion/Flags/BuildFlagsExtensions.cs | Added XML docs for BuildOptions extension anchor/factories. |
| src/Invex.Atom.Module.GithubWorkflows/Invex.Atom.Module.GithubWorkflows.csproj | Suppress CS1591 due to generated code. |
| src/Invex.Atom.Module.Dotnet/Invex.Atom.Module.Dotnet.csproj | Expand NoWarn to include CS1591; document generated-code rationale. |
| src/Invex.Atom.Module.DevopsWorkflows/Invex.Atom.Module.DevopsWorkflows.csproj | Suppress CS1591 due to generated code. |
| src/Invex.Atom.Module.AzureKeyVault/Options/UseAzureKeyVault.cs | Added XML docs for build option. |
| src/Invex.Atom.Module.AzureKeyVault/Options/AzureKeyVaultBuildOptionsExtensions.cs | Added XML docs for BuildOptions extension anchor/factories. |
| src/Invex.Atom.Build/Util/UnstableAPIAttribute.cs | Added XML docs clarifying stability expectations. |
| src/Invex.Atom.Build/Util/TaskExtensions.cs | Improved docs explaining retry semantics and overload intent. |
| src/Invex.Atom.Build/Secrets/ISecretsProvider.cs | Docs updated to reflect priority-based resolution ordering. |
| src/Invex.Atom.Build/Params/ParamDefinition.cs | Added XML docs for implicit string conversion. |
| src/Invex.Atom.Build/ISetupBuildInfo.cs | Updated docs/examples to match current variable consumption behavior. |
| src/Invex.Atom.Build/FileSystem/FileSystemExtensions.cs | Added XML docs for filesystem extension surface. |
| src/Invex.Atom.Build/FileSystem/AtomPaths.cs | Clarified purpose of Atom path keys in docs. |
| src/Invex.Atom.Build/Exceptions/CommandLineException.cs | Reframed docs: parsing collects errors; exception for later arg-related failures. |
| src/Invex.Atom.Build/Definition/TargetDefinition.cs | Small parameter naming fix and signature clarification. |
| src/Invex.Atom.Build/Definition/IBuildDefinition.cs | Doc typo fix (duplicate type reference). |
| src/Invex.Atom.Build/Definition/BuildDefinitionInterfaceAttribute.cs | Added XML docs for attribute purpose. |
| src/Invex.Atom.Build/BuildOptions/ToggleBuildOption.cs | Added XML docs for toggle semantics and querying. |
| src/Invex.Atom.Build/BuildOptions/IBuildOption.cs | Added XML docs for option purpose/usage. |
| src/Invex.Atom.Build/BuildOptions/BuildOptions.cs | Added XML docs for options extension anchor concept. |
| src/Invex.Atom.Build/BuildOptions/BuildOptionExtensions.cs | Added XML docs for option query helpers and “last wins” semantics. |
| src/Invex.Atom.Build/AtomService.cs | Switch invalid-args handling to structured console reporting; inject console. |
| src/Invex.Atom.Build/AtomProjectData.cs | Added XML docs. |
| src/Invex.Atom.Build/Args/ParseError.cs | New public type representing parse-time errors and suggestions. |
| src/Invex.Atom.Build/Args/CommandLineArgsParser.cs | Parser now collects errors instead of output/throwing; returns Errors. |
| src/Invex.Atom.Build/Args/CommandLineArgs.cs | Add Errors property and adjust validation error reporting. |
| src/Invex.Atom.Build.SourceGenerators/Symbols.cs | Reduce generator helper surface to internal. |
| src/Invex.Atom.Build.SourceGenerators/SetupSourceGenerator.cs | Added generator XML docs/inheritdoc. |
| src/Invex.Atom.Build.SourceGenerators/GenerateSolutionModelSourceGenerator.cs | Added generator XML docs/inheritdoc. |
| src/Invex.Atom.Build.SourceGenerators/GenerateInterfaceMembersSourceGenerator.cs | Added generator XML docs/inheritdoc. |
| src/Invex.Atom.Build.SourceGenerators/GenerateEntryPointSourceGenerator.cs | Added generator XML docs/inheritdoc. |
| src/Invex.Atom.Build.SourceGenerators/BuildDefinitionSourceGenerator.cs | Added generator XML docs; internalize helper extension type. |
| src/Invex.Atom.Build.SourceGenerators/BuildDefinitionInterfaceSourceGenerator.cs | Added generator XML docs/inheritdoc. |
| src/Invex.Atom.Build.Analyzers/AT0003_ConfigureHostBuilderPartialMethodNotImplementedCodeFixProvider.cs | Add inheritdoc comments. |
| src/Invex.Atom.Build.Analyzers/AT0003_ConfigureHostBuilderPartialMethodNotImplementedAnalyzer.cs | Add XML docs for analyzer constants/members. |
| src/Invex.Atom.Build.Analyzers/AT0002_ConfigureHostPartialMethodNotImplementedCodeFixProvider.cs | Add inheritdoc comments. |
| src/Invex.Atom.Build.Analyzers/AT0002_ConfigureHostPartialMethodNotImplementedAnalyzer.cs | Add XML docs for analyzer constants/members. |
| src/Invex.Atom.Build.Analyzers/AT0001_TargetRequiringParamShouldNotDirectlyReferenceParamCodeFixProvider.cs | Add inheritdoc comments. |
| src/Invex.Atom.Build.Analyzers/AT0001_TargetRequiringParamShouldNotDirectlyReferenceParamAnalyzer.cs | Add XML docs for analyzer constants/members. |
| samples/Sample_02_Params/Sample_02_Params.csproj | Suppress CS1591 for sample project. |
| samples/Sample_01_HelloWorld/Sample_01_HelloWorld.csproj | Suppress CS1591 for sample project. |
| samples/Invex.Atom.Analyzers.Sample/Invex.Atom.Analyzers.Sample.csproj | Suppress CS1591 for sample project. |
| docs/workflows/variables-in-workflows.md | Update variable semantics and examples to current behavior. |
| docs/workflows/triggers.md | Update manual trigger input examples and add tip. |
| docs/workflows/overview.md | Update Gen invocation text and workflow build definition feature list. |
| docs/workflows/debugging-workflows.md | Update Gen command and lifecycle hook behavior description. |
| docs/toc.yml | Rename docs nav entry for Gen. |
| docs/modules/overview.md | Clarify [ConfigureHostBuilder] method naming convention. |
| docs/modules/git-version.md | Document required build flags for provider activation. |
| docs/modules/dotnet.md | Clarify module surface area and workflow integration. |
| docs/getting-started/introduction.md | Update references from GenerateWorkflowFiles to Gen. |
| docs/getting-started/base-vs-workflow-build.md | Update example to include platform module interface; update Gen references. |
| docs/developer-guide/writing-a-module.md | Update module patterns; add BuildOptions guidance. |
| docs/developer-guide/source-generators.md | Update [ConfigureHostBuilder] description to new partial method naming. |
| docs/developer-guide/custom-providers.md | Update build-info provider examples to current types. |
| docs/core-concepts/variables.md | Update variable model and examples (backing param, persistence). |
| docs/core-concepts/targets.md | Adjust dependency and extension ordering docs. |
| docs/core-concepts/secrets.md | Document secrets provider priority ordering. |
| docs/core-concepts/lifecycle-hooks.md | Update workflow lifecycle behavior description. |
| docs/core-concepts/hosting.md | Update [ConfigureHostBuilder] method naming conventions. |
| docs/core-concepts/file-system.md | Update signature example for path marker. |
| docs/core-concepts/build-info.md | Update build info types/defaults and CLI override info. |
| docs/core-concepts/artifacts.md | Clarify native vs custom artifact provider behavior. |
| docs/built-in-targets/generate-workflow-files.md | Rename and rewrite page for Gen and new writer API. |
| docfx.json | Remove deprecated/removed projects from DocFX metadata input. |
| Directory.Build.props | Remove global CS1591 suppression to enforce docs in src/. |
| .github/copilot-instructions.md | Add repo-specific Copilot guidance (structure, conventions, workflows, testing). |
| _atom/_atom.csproj | Suppress CS1591 in the _atom build project. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This was referenced Jun 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces a set of documentation and configuration improvements to the Atom build automation framework. The most significant changes include the addition of comprehensive Copilot instructions, updates to documentation for clarity and accuracy, and adjustments to code analysis warning suppression. These updates enhance the onboarding experience for contributors, clarify architectural concepts, and improve the maintainability of the project.
Documentation Enhancements:
.github/copilot-instructions.mdto guide AI agents and contributors on the structure, conventions, and workflows of the Atom repository, including project roles, build/test instructions, architecture overview, and contribution guidelines.docs/core-concepts/,docs/built-in-targets/, etc.) to clarify concepts such as artifact providers, build info, file system paths, hosting, lifecycle hooks, secrets, and target dependencies. Notable improvements include updated provider APIs, clearer explanations of workflow generation, and corrections to extension behavior and dependency resolution. [1] [2] [3] [4] [5] [6] [7] [8]Workflow and Build Configuration:
Gentarget, automatic regeneration behavior, and platform output locations.docfx.jsonto remove references to deprecated or removed projects, ensuring documentation generation reflects the current state of the codebase.Code Analysis and Warning Suppression:
CS1591) by removing it from the globalDirectory.Build.propsand scoping it locally to the_atomproject, enforcing stricter documentation requirements in source projects while allowing flexibility for the build definition. [1] [2]