Add comprehensive documentation files for IComparable Extensions#8
Conversation
…ction.md, readme.md, setup.md) Co-authored-by: Chris-Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com>
…cation Co-authored-by: Chris-Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a set of documentation pages under /docs for the Wolfgang.Extensions.IComparable library, including usage guidance and contributor setup instructions.
Changes:
- Added library overview and conceptual introduction (
docs/introduction.md) - Added installation + usage guide with examples (
docs/getting-started.md) - Added longer-form API/reference doc with examples (
docs/readme.md) - Added contributor/development environment setup guide (
docs/setup.md)
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 12 comments.
| File | Description |
|---|---|
| docs/introduction.md | Adds an introductory overview and basic examples for the library |
| docs/getting-started.md | Adds installation and basic usage documentation with code samples |
| docs/readme.md | Adds expanded usage examples, API reference, and support/contributing links |
| docs/setup.md | Adds contributor setup, build/test/coverage guidance, and workflow notes |
| - Write code following the existing style | ||
| - Add or update tests for your changes | ||
| - Ensure tests pass: `dotnet test` | ||
| - Ensure coverage meets requirements (≥80%) |
There was a problem hiding this comment.
The documented coverage requirement (≥80%) doesn’t match the actual CI gate in .github/workflows/pr.yaml, which enforces 90% coverage. Please update the documented threshold to match CI so contributors don’t get surprised by failing checks.
| - Ensure coverage meets requirements (≥80%) | |
| - Ensure coverage meets requirements (≥90%) |
|
|
||
| ```bash | ||
| # Run only unit tests | ||
| dotnet test tests/Wolfgang.Extensions.IComparable.Tests/Wolfgang.Extensions.IComparable.Tests.csproj |
There was a problem hiding this comment.
This command references tests/Wolfgang.Extensions.IComparable.Tests/..., but the repo’s test project folder is tests/Wolfgang.Extensions.IComparable.Tests.Unit/... (see tests/). Please update the path so the command works as written.
| dotnet test tests/Wolfgang.Extensions.IComparable.Tests/Wolfgang.Extensions.IComparable.Tests.csproj | |
| dotnet test tests/Wolfgang.Extensions.IComparable.Tests.Unit/Wolfgang.Extensions.IComparable.Tests.Unit.csproj |
| │ └── Wolfgang.Extensions.IComparable.Tests/ | ||
| │ ├── Wolfgang.Extensions.IComparable.Tests.csproj |
There was a problem hiding this comment.
The project structure diagram lists tests/Wolfgang.Extensions.IComparable.Tests/, but the repository currently uses tests/Wolfgang.Extensions.IComparable.Tests.Unit/. Please update the diagram to match the actual folder/project names.
| │ └── Wolfgang.Extensions.IComparable.Tests/ | |
| │ ├── Wolfgang.Extensions.IComparable.Tests.csproj | |
| │ └── Wolfgang.Extensions.IComparable.Tests.Unit/ | |
| │ ├── Wolfgang.Extensions.IComparable.Tests.Unit.csproj |
|
|
||
| ## License | ||
|
|
||
| This project is licensed under the [Mozilla Public License 2.0](../LICENSE). |
There was a problem hiding this comment.
The license referenced here (Mozilla Public License 2.0) doesn’t match the repository’s LICENSE file (MIT). Please update this section to reference MIT so docs and packaging metadata are consistent.
| This project is licensed under the [Mozilla Public License 2.0](../LICENSE). | |
| This project is licensed under the [MIT License](../LICENSE). |
|
|
||
| ## License | ||
|
|
||
| This project is licensed under the Mozilla Public License 2.0. See the [LICENSE](../LICENSE) file for details. |
There was a problem hiding this comment.
This section states the project is licensed under MPL 2.0, but the repository’s LICENSE file is MIT. Please update the text/link to reflect the actual MIT license.
| This project is licensed under the Mozilla Public License 2.0. See the [LICENSE](../LICENSE) file for details. | |
| This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details. |
|
|
||
| ## Requirements | ||
|
|
||
| - .NET 8.0 or later |
There was a problem hiding this comment.
The “Requirements” section says “.NET 8.0 or later”, but the library targets net462 and netstandard2.0 (and tests run across multiple TFMs). Please adjust this to reflect the actual supported target frameworks so consumers on older TFMs aren’t incorrectly excluded.
| - .NET 8.0 or later | |
| - .NET Framework 4.6.2 or later | |
| - Any platform that supports .NET Standard 2.0 (e.g., .NET Core 2.0+, .NET 5+, .NET 6+, .NET 8+) |
| 1. Navigate to [https://github.com/Chris-Wolfgang/IComparable-Extensions](https://github.com/Chris-Wolfgang/IComparable-Extensions) | ||
| 2. Click the **Fork** button in the upper right | ||
| 3. Select your GitHub account as the destination | ||
|
|
||
| ### 2. Clone Your Fork | ||
|
|
||
| ```bash | ||
| # Clone your fork | ||
| git clone https://github.com/YOUR-USERNAME/IComparable-Extensions.git | ||
|
|
||
| # Navigate to the repository | ||
| cd IComparable-Extensions | ||
|
|
||
| # Add upstream remote | ||
| git remote add upstream https://github.com/Chris-Wolfgang/IComparable-Extensions.git | ||
| ``` |
There was a problem hiding this comment.
These GitHub URLs point to Chris-Wolfgang/IComparable-Extensions, but the package metadata uses https://github.com/Chris-Wolfgang/Wolfgang.Extensions.IComparable (see src/Wolfgang.Extensions.IComparable/Wolfgang.Extensions.IComparable.csproj). Please align the documentation with the canonical repo URL to avoid sending users to the wrong project.
| | Method | Comparison Type | Lower Bound | Upper Bound | Example | | ||
| |--------|----------------|-------------|-------------|---------| | ||
| | `IsBetween` | Exclusive | `>` | `<` | `5.IsBetween(1, 10)` → `true` | | ||
| | `IsInRange` | Inclusive | `>=` | `<=` | `1.IsInRange(1, 10)` → `true` | |
There was a problem hiding this comment.
The quick reference table has an extra leading | on each row (e.g., starts with || Method ...). This renders as an empty first column in Markdown. Remove the extra leading pipe so the table is formatted correctly.
| public int CompareTo(Employee other) | ||
| { |
There was a problem hiding this comment.
This IComparable<Employee> example won’t match the .NET IComparable<T> signature under nullable reference types (CompareTo(T? other)), which can produce warnings (and may fail builds if warnings are treated as errors). Consider changing the signature to CompareTo(Employee? other) and handling null explicitly.
| public int CompareTo(Employee other) | |
| { | |
| public int CompareTo(Employee? other) | |
| { | |
| if (other is null) | |
| { | |
| // By convention, any instance is greater than null | |
| return 1; | |
| } |
| public class Version : IComparable<Version> | ||
| { | ||
| public int Major { get; set; } | ||
| public int Minor { get; set; } | ||
|
|
||
| public int CompareTo(Version other) | ||
| { | ||
| int result = Major.CompareTo(other.Major); | ||
| return result != 0 ? result : Minor.CompareTo(other.Minor); | ||
| } | ||
| } | ||
|
|
||
| var currentVersion = new Version { Major = 2, Minor = 5 }; | ||
| var minVersion = new Version { Major = 2, Minor = 0 }; | ||
| var maxVersion = new Version { Major = 3, Minor = 0 }; |
There was a problem hiding this comment.
This custom type example uses the name Version, which collides with System.Version and can confuse consumers. Also, with nullable reference types enabled, IComparable<T>’s signature is CompareTo(T? other); using a non-nullable parameter can produce nullability mismatch warnings. Consider renaming the type (e.g., SemanticVersion) and updating CompareTo to accept a nullable parameter and handle null.
| public class Version : IComparable<Version> | |
| { | |
| public int Major { get; set; } | |
| public int Minor { get; set; } | |
| public int CompareTo(Version other) | |
| { | |
| int result = Major.CompareTo(other.Major); | |
| return result != 0 ? result : Minor.CompareTo(other.Minor); | |
| } | |
| } | |
| var currentVersion = new Version { Major = 2, Minor = 5 }; | |
| var minVersion = new Version { Major = 2, Minor = 0 }; | |
| var maxVersion = new Version { Major = 3, Minor = 0 }; | |
| public class SemanticVersion : IComparable<SemanticVersion> | |
| { | |
| public int Major { get; set; } | |
| public int Minor { get; set; } | |
| public int CompareTo(SemanticVersion? other) | |
| { | |
| if (other is null) | |
| { | |
| return 1; | |
| } | |
| int result = Major.CompareTo(other.Major); | |
| return result != 0 ? result : Minor.CompareTo(other.Minor); | |
| } | |
| } | |
| var currentVersion = new SemanticVersion { Major = 2, Minor = 5 }; | |
| var minVersion = new SemanticVersion { Major = 2, Minor = 0 }; | |
| var maxVersion = new SemanticVersion { Major = 3, Minor = 0 }; |
Three Copilot review findings on the v1.1.1 vNext PR — all valid: 1. CONTRIBUTING.md 'The 7 Analyzers' undercounted. The A1 canonical sync added Microsoft.CodeAnalysis.PublicApiAnalyzers to Directory.Build.props, bringing the total to 8. Updated the heading + added entry #8 explaining the per-project Exists() activation model. 2. docs/DOCFX-VERSION-PICKER.md claimed 'scripts/Validate-DocsDeploy.sh runs at the end of every deploy'. It doesn't — grep confirms zero references in .github/. Reworded to describe it accurately as a manual post-deploy validation script + showed the invocation. 3. docfx_project/docfx.json's resource.files list only included 'images/**'. The _appFooter loads /public/version-picker.js and the picker reads /versions.json — neither would have been copied to _site/ on build, so the picker would silently 404 on the deployed site. Added 'public/**' and 'versions.json' to match the DateTime-Extensions canonical (which has both since their working v1.3.1 picker deployment).
Description
Created four documentation files in
/docsproviding complete library reference, usage guides, and contributor setup instructions.Type of change
How Has This Been Tested?
Checklist
Additional context
Files Created (880 lines total)
introduction.md(82 lines) - Library overview, IComparable explanation, key features, use cases, supported typesgetting-started.md(191 lines) - Installation methods (NuGet, Package Manager, .csproj), basic usage patterns, examples across numeric/date/string/custom types, troubleshootingreadme.md(250 lines) - Complete API reference, real-world implementations (validation, business logic, game dev, financial apps), performance characteristicssetup.md(357 lines) - Development environment configuration, fork/clone workflow, build/test procedures, CI/CD simulation, editor setup (VS Code/VS/Rider)Key Details
DateTime.Now) to prevent staleness1.*for reproducible buildsIsBetween(exclusive) vsIsInRange(inclusive)Original prompt
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.