Repository navigation
Improve library documentation and unattended usage examples - #435
Merged
Merged
Conversation
shibayan
added
documentation
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
The remaining feedback is a minor documentation clarification, with no identified blocking correctness issues.
1 open issue
What changed in this PR
This PR makes Sharprompt’s APIs easier to understand and its examples verifiable without an interactive terminal.
Changes:
- Adds XML documentation for public APIs and shared internals, enforces public documentation, and verifies XML packaging.
- Adds bilingual usage/testing guides, corrects README examples, and checks examples with both source generators.
- Adds an unattended sample, Markdown exports, discovery links, and supporting CI checks.
| File | Description |
|---|---|
| tests/Sharprompt.SourceGenerator.Tests/Sharprompt.SourceGenerator.Tests.csproj | Copies documentation examples into test output. |
| tests/Sharprompt.SourceGenerator.Tests/DocumentationExamplesTests.cs | Compiles documentation snippets with both generators. |
| src/Sharprompt/Validators.cs | Documents validator behavior. |
| src/Sharprompt/Symbol.cs | Documents symbol encoding fallbacks. |
| src/Sharprompt/Sharprompt.csproj | Enables XML output and documentation enforcement. |
| src/Sharprompt/SelectOptions.cs | Documents single-selection settings. |
| src/Sharprompt/PromptOptions.cs | Documents shared prompt settings. |
| src/Sharprompt/PromptConfiguration.cs | Documents configuration, colors, and symbols. |
| src/Sharprompt/PromptCanceledException.cs | Documents user-cancellation exceptions. |
| src/Sharprompt/PromptBindableAttribute.cs | Documents generated binding requirements. |
| src/Sharprompt/Prompt.Configuration.cs | Documents process-wide configuration accessors. |
| src/Sharprompt/Prompt.Bind.cs | Documents binding overloads and constraints. |
| src/Sharprompt/Prompt.Basic.cs | Documents prompt entry points and cancellation. |
| src/Sharprompt/PasswordOptions.cs | Documents password settings and validation. |
| src/Sharprompt/MultiSelectOptions.cs | Documents multiple-selection settings. |
| src/Sharprompt/ModelBinderRegistry.cs | Documents binder registration and lookup. |
| src/Sharprompt/MemberItemsAttribute.cs | Documents static item providers. |
| src/Sharprompt/ListOptions.cs | Documents list defaults and limits. |
| src/Sharprompt/Internal/ValidatorsExtensions.cs | Documents validator merging. |
| src/Sharprompt/Internal/TypeHelper.cs | Documents invariant-culture conversion. |
| src/Sharprompt/Internal/TextInputBuffer.cs | Documents text editing and cursor movement. |
| src/Sharprompt/Internal/RenderScope.cs | Documents scoped redraw behavior. |
| src/Sharprompt/Internal/Paginator.cs | Documents pagination and navigation. |
| src/Sharprompt/Internal/Optional.cs | Documents optional-value semantics. |
| src/Sharprompt/Internal/OffscreenBufferExtensions.cs | Documents prompt-component rendering. |
| src/Sharprompt/Internal/OffscreenBuffer.cs | Documents output buffering and coordinates. |
| src/Sharprompt/Internal/NativeMethods.cs | Documents Windows console interop. |
| src/Sharprompt/Internal/EastAsianWidth.cs | Documents terminal-width estimation. |
| src/Sharprompt/Internal/ConsoleText.cs | Documents text normalization and measurement. |
| src/Sharprompt/Internal/ConsoleKeyBinding.cs | Documents key matching and equality. |
| src/Sharprompt/InputOptions.cs | Documents input defaults and validators. |
| src/Sharprompt/InlineItemsAttribute.cs | Documents constant selection items. |
| src/Sharprompt/Forms/TextFormBase.cs | Documents text-editing handlers. |
| src/Sharprompt/Forms/SelectFormBase.cs | Documents shared selection behavior. |
| src/Sharprompt/Forms/SelectForm.cs | Documents single-selection lifecycle. |
| src/Sharprompt/Forms/PasswordForm.cs | Documents masking and validation retries. |
| src/Sharprompt/Forms/MultiSelectForm.cs | Documents checked-item handling. |
| src/Sharprompt/Forms/ListForm.cs | Documents list entry and completion. |
| src/Sharprompt/Forms/InputForm.cs | Documents conversion and editable defaults. |
| src/Sharprompt/Forms/FormRenderer.cs | Documents template and error rendering. |
| src/Sharprompt/Forms/FormBase.cs | Documents prompt lifecycle and cancellation. |
| src/Sharprompt/Forms/ConfirmForm.cs | Documents localized confirmation behavior. |
| src/Sharprompt/Fluent/SelectOptionsExtensions.cs | Documents fluent selection configuration. |
| src/Sharprompt/Fluent/PasswordOptionsExtensions.cs | Documents fluent password configuration. |
| src/Sharprompt/Fluent/MultiSelectOptionsExtensions.cs | Documents fluent multiple-selection configuration. |
| src/Sharprompt/Fluent/ListOptionsExtensions.cs | Documents fluent list configuration. |
| src/Sharprompt/Fluent/InputOptionsExtensions.cs | Documents fluent input configuration. |
| src/Sharprompt/Fluent/ConfirmOptionsExtensions.cs | Documents fluent confirmation configuration. |
| src/Sharprompt/EnumMetadataRegistry.cs | Documents enum metadata registration and fallback. |
| src/Sharprompt/Drivers/IConsoleDriver.cs | Documents custom console-driver responsibilities. |
| src/Sharprompt/Drivers/DefaultConsoleDriver.cs | Documents terminal-driver behavior. |
| src/Sharprompt/ConfirmOptions.cs | Documents confirmation defaults. |
| src/Sharprompt/BindIgnoreAttribute.cs | Documents binding exclusion. |
| src/Sharprompt.SourceGenerator/Sharprompt.SourceGenerator.csproj | Enables generator XML documentation enforcement. |
| src/Sharprompt.SourceGenerator/PromptBindableGenerator.cs | Documents the binding generator pipeline. |
| src/Sharprompt.SourceGenerator/EnumMetadataGenerator.cs | Documents the enum generator pipeline. |
| Sharprompt.slnx | Adds the automation sample to the solution. |
| samples/Sharprompt.Automation/Sharprompt.Automation.csproj | Configures the dual-framework sample and generators. |
| samples/Sharprompt.Automation/ScriptedConsoleDriver.cs | Adds deterministic unattended input. |
| samples/Sharprompt.Automation/Program.cs | Exercises prompts, binding, retries, and cancellation. |
| README.md | Corrects snippets and links new guides. |
| docs/scripts/export-markdown.mjs | Generates Markdown pages and llms.txt. |
| docs/README.md | Explains documentation development and exports. |
| docs/package.json | Runs Markdown export after site generation. |
| docs/ja/usage-guide.md | Adds the Japanese usage guide. |
| docs/ja/testing.md | Adds the Japanese testing guide. |
| docs/en/usage-guide.md | Adds the English usage guide. |
| docs/en/testing.md | Adds the English testing guide. |
| docs/.vitepress/config.mts | Adds guide navigation and discovery links. |
| CONTRIBUTING.md | Updates prerequisites and verification guidance. |
| .github/workflows/docs.yml | Rebuilds published docs when sample sources change. |
| .github/workflows/docs-ci.yml | Checks docs when sample sources change. |
| .github/workflows/build.yml | Runs automation examples and verifies packaged XML. |
Review effort: Balanced
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.
Consumers and coding agents currently have to infer API behavior from source and cannot verify interactive examples in unattended environments. Add XML documentation for public APIs and shared internals, ship the library XML in NuGet, and fail builds when public documentation is missing.
Add English and Japanese usage and testing guides, fix README snippets and compile them with both source generators in tests, and provide a scripted console sample covering all prompt types, validation retries, binding, and cancellation. Generate Markdown exports and an llms.txt index from the existing documentation, with discovery links in HTML and CI checks for the sample and packaged XML.
Validation: