Enhance XML documentation and README for public APIs and usage - #315
Merged
Merged
Conversation
Clarified that AddOperationParameters registers the operation transformer for OpenAPI parameters and added guidance to call the parameter registration method first. Improved remarks and references for better developer understanding.
Added /src/TinyHelpers/TinyHelpers.xml and /src/TinyHelpers.AspNetCore/TinyHelpers.AspNetCore.xml to .gitignore to prevent these XML files from being tracked by Git. This helps keep generated or documentation files out of version control.
Added and improved XML documentation comments across public APIs, including class-level summaries, remarks, and parameter/return value details. Introduced <inheritdoc /> tags for overridden members. Added missing using directives to support documentation. Updated project file to generate and exclude XML docs from package content. Minor code style and formatting improvements for clarity and consistency.
Expanded and improved XML documentation across multiple files to better explain the purpose, usage, and intent of public APIs. Enhanced <remarks> sections to clarify design decisions and usage scenarios, and improved parameter and return value descriptions. No functional changes; all updates are documentation improvements.
Added /src/TinyHelpers.AspNetCore.Swashbuckle/TinyHelpers.AspNetCore.Swashbuckle.xml to .gitignore to prevent the XML documentation file from being tracked by Git. This helps keep generated or build output files out of version control.
Added <DocumentationFile> to generate TinyHelpers.AspNetCore.Swashbuckle.xml during build. Excluded any pre-existing XML documentation file from the project output to prevent conflicts.
Expanded and refined documentation for API methods, especially OpenAPI and validation features. Improved descriptions, added usage rationale, clarified framework-specific availability, and enhanced examples for parameter registration and schema helpers to aid developer understanding and integration.
Improved and expanded XML documentation for OpenApiOperationOptions and related Swagger extension methods to clarify their purpose and usage. Enhanced code comments for maintainability. Fixed a typo in the .csproj file for the XML documentation file name.
Expanded and clarified documentation for TinyHelpers.AspNetCore.Swashbuckle. Improved descriptions of extension methods, updated tables for SwaggerExtensions and OpenApiSchemaHelper, and revised code examples to better illustrate parameter registration and usage. Added guidance on shared parameter registration and clarified schema helper method scenarios.
Expanded XML doc comments and README guidance for all helpers. Enhanced method summaries, usage scenarios, and parameter/return docs for better clarity and discoverability. No functional code changes.
There was a problem hiding this comment.
Pull request overview
This PR improves the consumer-facing documentation for TinyHelpers and its ASP.NET Core / Swashbuckle packages by expanding XML docs and README guidance, and it enables XML documentation generation for the ASP.NET Core packages so IntelliSense can surface those docs to consumers.
Changes:
- Expanded/clarified XML documentation across core helpers, HTTP handlers, JSON converters, and OpenAPI/Swagger integration points.
- Updated README files with clearer “what/why/when” usage guidance and improved OpenAPI/Swagger examples.
- Enabled XML documentation file generation for
TinyHelpers.AspNetCoreandTinyHelpers.AspNetCore.Swashbuckle, and ignored generated XML outputs in.gitignore.
Reviewed changes
Copilot reviewed 31 out of 32 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/TinyHelpers/Threading/LockResult.cs | Clarifies LockResult semantics for timed lock acquisition (XML docs). |
| src/TinyHelpers/Threading/AsyncLock.cs | Expands AsyncLock usage guidance and timed-lock behavior (XML docs). |
| src/TinyHelpers/Json/Serialization/UtcDateTimeConverter.cs | Updates converter documentation to explain UTC normalization intent (XML docs). |
| src/TinyHelpers/Json/Serialization/TimeSpanTicksConverter.cs | Improves converter summary wording (XML docs). |
| src/TinyHelpers/Json/Serialization/StringTrimmingConverter.cs | Adds rationale/usage remarks for trimming converter (XML docs). |
| src/TinyHelpers/Json/Serialization/ShortDateConverter.cs | Adds rationale/usage remarks for date-only contract converter (XML docs). |
| src/TinyHelpers/Http/QueryStringInjectorHttpClientHandler.cs | Clarifies when/why to centralize query-string injection (XML docs). |
| src/TinyHelpers/Http/HeaderInjectorHttpClientHandler.cs | Clarifies when/why to centralize header injection (XML docs). |
| src/TinyHelpers/Http/AuthenticatedParameterizedHttpClientHandler.cs | Clarifies token injection + refresh-on-401 behavior (XML docs). |
| src/TinyHelpers/Extensions/GuidExtensions.cs | Improves guidance around treating Guid.Empty as “missing” (XML docs). |
| src/TinyHelpers/Extensions/DateTimeOffsetExtensions.cs | Aligns ToTimeOnly behavior with documented time-zone application. |
| src/TinyHelpers/Extensions/CollectionExtensions.cs | Improves docs for fluent/conditional collection helpers (XML docs). |
| src/TinyHelpers.AspNetCore/TinyHelpers.AspNetCore.csproj | Enables XML doc output for consumers; excludes XML from pack content. |
| src/TinyHelpers.AspNetCore/README.md | Expands usage guidance and OpenAPI helper documentation/examples. |
| src/TinyHelpers.AspNetCore/OpenApi/Transformers/TimeExampleSchemaTransformer.cs | Adds XML docs for time-example schema transformer. |
| src/TinyHelpers.AspNetCore/OpenApi/Transformers/OpenApiOperationOptions.cs | Clarifies purpose/contract for shared OpenAPI operation options. |
| src/TinyHelpers.AspNetCore/OpenApi/Transformers/DefaultResponseOperationTransformer.cs | Documents default problem-details response behavior and options. |
| src/TinyHelpers.AspNetCore/OpenApi/Transformers/CamelCaseQueryParametersOperationTransformer.cs | Adds XML docs for query-parameter camel-casing transformer. |
| src/TinyHelpers.AspNetCore/OpenApi/OpenApiSchemaHelper.cs | Expands docs to describe schema factory intent/consistency. |
| src/TinyHelpers.AspNetCore/OpenApi/OpenApiExtensions.cs | Clarifies responsibilities and usage patterns for OpenAPI extensions. |
| src/TinyHelpers.AspNetCore/Middlewares/ApplicationBuilderExtensions.cs | Clarifies intent of request rewind middleware registration helper. |
| src/TinyHelpers.AspNetCore/Extensions/ServiceCollectionExtensions.cs | Adds richer remarks for localization, replacement, and ProblemDetails setup helpers. |
| src/TinyHelpers.AspNetCore/Extensions/RouteHandlerBuilderExtensions.cs | Improves docs for minimal-API OpenAPI metadata helpers. |
| src/TinyHelpers.AspNetCore/DataAnnotations/FileSizeAttribute.cs | Adds/extends contract-focused docs for upload validation. |
| src/TinyHelpers.AspNetCore/DataAnnotations/ContentTypeAttribute.cs | Adds enum member docs + expands attribute contract/usage guidance. |
| src/TinyHelpers.AspNetCore/DataAnnotations/AllowedExtensionsAttribute.cs | Expands remarks to explain contract enforcement intent. |
| src/TinyHelpers.AspNetCore.Swashbuckle/TinyHelpers.AspNetCore.Swashbuckle.csproj | Enables XML doc output for consumers; excludes XML from pack content. |
| src/TinyHelpers.AspNetCore.Swashbuckle/SwaggerExtensions.cs | Clarifies “register vs apply” shared-parameter Swagger workflow (XML docs). |
| src/TinyHelpers.AspNetCore.Swashbuckle/README.md | Improves Swagger usage guidance and shared-parameter example sequencing. |
| src/TinyHelpers.AspNetCore.Swashbuckle/Filters/OpenApiOperationOptions.cs | Clarifies purpose/contract for shared Swagger operation options. |
| README.md | Improves overall library README explanations and usage descriptions. |
| .gitignore | Ignores generated XML documentation files for the added projects. |
Comment on lines
6
to
10
| /// <summary> | ||
| /// A converter for serializing and deserializing <see cref="DateTime"/> values converting them to UTC, if needed. | ||
| /// Converts <see cref="DateTime" /> values to UTC during JSON serialization and deserialization. | ||
| /// </summary> | ||
| /// <seealso cref="DateTime"/> | ||
| /// <remarks> |
Comment on lines
3
to
5
| /// <summary> | ||
| /// Represents the result of an asynchronous lock operation. | ||
| /// Represents the outcome of a timed <see cref="Threading.AsyncLock" /> acquisition attempt. | ||
| /// </summary> |
Comment on lines
12
to
14
| /// <summary> | ||
| /// Gets the <seealso cref="Threading.AsyncLock"/> object if successfully acquired. | ||
| /// Gets the <see cref="Threading.AsyncLock" /> instance to dispose when the lock was acquired. | ||
| /// </summary> |
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 focuses on improving the documentation, clarity, and usability of both the main
TinyHelperslibrary and theTinyHelpers.AspNetCore.Swashbucklepackage. The changes make the libraries' contracts, extension methods, and Swagger integration points more explicit and easier to understand for consumers. The most important changes are grouped below.Documentation and Usability Improvements
README.mdfiles for both packages, making it clearer when and why to use each helper or extension method. This includes more explicit descriptions of method contracts, scenarios, and improved table explanations for collection, date/time, GUID, HTTP, and JSON helpers. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13]Swagger and OpenAPI Integration Enhancements
OpenApiOperationOptionsclass and related Swagger extension methods, making it clear that shared parameters should be registered once and are automatically injected into generated Swagger operations. This prevents duplicated endpoint metadata and keeps the OpenAPI contract consistent. [1] [2] [3]Project and Build Improvements
<DocumentationFile>entry to the Swashbuckle package project file to generate XML documentation for consumers, and ensured the XML file is not accidentally included as content. [1] [2]These changes collectively make the libraries easier to use, reduce ambiguity for consumers, and improve the maintainability and discoverability of shared helpers and Swagger integration points.