From 98f4299ce1e6b87b208544e56f3243f8f22191d6 Mon Sep 17 00:00:00 2001 From: leecampbell-codeagent Date: Sun, 1 Mar 2026 09:09:53 +0000 Subject: [PATCH 1/5] plan(#106): initial brief from issue --- plan/planning/brief.md | 48 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 plan/planning/brief.md diff --git a/plan/planning/brief.md b/plan/planning/brief.md new file mode 100644 index 0000000..f8075e8 --- /dev/null +++ b/plan/planning/brief.md @@ -0,0 +1,48 @@ +# Issue #106: Fix Unresolved XML cref in Bitwise.cs for netstandard2.0 + +## Summary + +The build produces a `CS1574` warning when compiling `HdrHistogram.csproj` for the `netstandard2.0` target. +The XML doc comment on the `Imperative` nested class inside `HdrHistogram/Utilities/Bitwise.cs` (line 53) contains a `` reference. +`System.Numerics.BitOperations` was introduced in .NET Core 3.0 and is not part of the `netstandard2.0` API surface, so the compiler cannot resolve the `cref` and emits a warning. + +The fix is to change the XML doc comment so the reference is expressed as plain formatted code (using ``) rather than a resolvable `cref`, eliminating the warning for all target frameworks without altering runtime behaviour. + +## Affected Files + +- `HdrHistogram/Utilities/Bitwise.cs` — line 53, XML `` doc comment on the `Imperative` class (the only change required) + +## What Needs to Change and Why + +| Location | Current | Problem | +|----------|---------|---------| +| `Bitwise.cs:53` | `` | `System.Numerics.BitOperations` does not exist in `netstandard2.0`; compiler emits `CS1574` | + +Replace the `` with `System.Numerics.BitOperations.LeadingZeroCount(ulong)`. +This preserves the intent (showing the fully-qualified method name in a monospace code style) without requiring the compiler to resolve a type that is absent from the `netstandard2.0` reference assembly set. + +No conditional compilation (`#if`) is needed; plain `` is the minimal, least-intrusive change. + +## Acceptance Criteria + +- Building `HdrHistogram.csproj` with `dotnet build -f netstandard2.0` produces **no** `CS1574` warning. +- Building `HdrHistogram.csproj` with `dotnet build -f net8.0` continues to succeed without new warnings. +- The generated XML documentation for `Imperative` still describes its purpose clearly. +- No runtime behaviour changes (the fix is doc-comment only). + +## Test Strategy + +The issue is confined to an XML doc comment; no logic changes, so no new unit tests are required. +Verification is via the build itself: + +1. Run `dotnet build HdrHistogram/HdrHistogram.csproj -f netstandard2.0 /warnaserror:CS1574` — must exit 0. +2. Run `dotnet build HdrHistogram/HdrHistogram.csproj -f net8.0` — must exit 0. +3. Run the existing test suite (`dotnet test`) to confirm no regressions. + +## Risks and Open Questions + +- **Minimal risk**: The change is one line inside a doc comment; it cannot affect compiled IL or runtime behaviour. +- **Open question**: Should `CS1574` be promoted to an error in the project file (`` or `CS1574`) to prevent recurrence? + This would be a separate, optional hardening step and is out of scope for this issue. +- **Alternative considered**: Using `#if NET5_0_OR_GREATER` ... `#else` conditional compilation around the entire `` block. + This works but is significantly more verbose for no additional benefit over a simple `` tag. From ee17e53284ac4b0306d55fd1f791fe4bf4119af7 Mon Sep 17 00:00:00 2001 From: leecampbell-codeagent Date: Sun, 1 Mar 2026 09:11:43 +0000 Subject: [PATCH 2/5] plan(#106): review brief --- plan/{planning => ready}/brief.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename plan/{planning => ready}/brief.md (100%) diff --git a/plan/planning/brief.md b/plan/ready/brief.md similarity index 100% rename from plan/planning/brief.md rename to plan/ready/brief.md From 088b22cf794a1f46f402ecf9dedeec7dd761eb88 Mon Sep 17 00:00:00 2001 From: leecampbell-codeagent Date: Sun, 1 Mar 2026 09:13:58 +0000 Subject: [PATCH 3/5] plan(#106): create task breakdown --- plan/ready/task.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 plan/ready/task.md diff --git a/plan/ready/task.md b/plan/ready/task.md new file mode 100644 index 0000000..4d5b042 --- /dev/null +++ b/plan/ready/task.md @@ -0,0 +1,54 @@ +# Task List: Fix Unresolved XML cref in Bitwise.cs (#106) + +## Context + +`HdrHistogram/Utilities/Bitwise.cs` line 53 has an XML doc `` on the `Imperative` nested class summary. +`System.Numerics.BitOperations` does not exist in `netstandard2.0`, so the compiler emits a `CS1574` warning for that target framework. +The fix is a one-line doc-comment change; no logic or tests need to change. + +--- + +## Tasks + +### Implementation + +- [ ] **Fix XML cref in `HdrHistogram/Utilities/Bitwise.cs:53`** + - **File:** `HdrHistogram/Utilities/Bitwise.cs` + - **Line:** 53 (the `` of the `Imperative` nested class) + - **Change:** Replace `` with `System.Numerics.BitOperations.LeadingZeroCount(ulong)` + - **Why:** `System.Numerics.BitOperations` is not part of the `netstandard2.0` API surface; using `` renders the method name in monospace without requiring compiler resolution. + - **Verify:** The word `cref` no longer appears in that `` block; the method name is still present as formatted code. + +--- + +### Build Verification + +- [ ] **Build for `netstandard2.0` with CS1574 treated as error** + - **Command:** `dotnet build HdrHistogram/HdrHistogram.csproj -f netstandard2.0 /warnaserror:CS1574` + - **Why:** Directly validates acceptance criterion 1 — no `CS1574` warning on the `netstandard2.0` target. + - **Verify:** Command exits with code 0 and no `CS1574` diagnostic appears in output. + +- [ ] **Build for `net8.0`** + - **Command:** `dotnet build HdrHistogram/HdrHistogram.csproj -f net8.0` + - **Why:** Validates acceptance criterion 2 — the fix must not introduce new warnings or errors on the modern target framework. + - **Verify:** Command exits with code 0; output contains no new warnings or errors compared to pre-fix baseline. + +--- + +### Regression Testing + +- [ ] **Run the full test suite** + - **Command:** `dotnet test` + - **Why:** Confirms no regressions from the doc-comment change (the fix is IL-invisible, but CI must stay green). + - **Verify:** All tests pass; no test failures or errors reported. + +--- + +## Acceptance Criteria Cross-Reference + +| Acceptance Criterion (from brief) | Covered by Task | +|-----------------------------------|-----------------| +| `dotnet build -f netstandard2.0` produces no `CS1574` warning | Build for `netstandard2.0` with CS1574 treated as error | +| `dotnet build -f net8.0` continues to succeed without new warnings | Build for `net8.0` | +| Generated XML documentation for `Imperative` still describes its purpose clearly | Fix XML cref (method name retained as `` text) | +| No runtime behaviour changes | Fix XML cref (doc-comment only; no IL change) + full test suite | From 23f91b2a652210b1e351f8db2272157e0a8a0d50 Mon Sep 17 00:00:00 2001 From: leecampbell-codeagent Date: Sun, 1 Mar 2026 09:17:58 +0000 Subject: [PATCH 4/5] feat(#106): implement tasks --- HdrHistogram/Utilities/Bitwise.cs | 2 +- plan/{ready => done}/brief.md | 0 plan/{ready => done}/task.md | 8 ++++---- 3 files changed, 5 insertions(+), 5 deletions(-) rename plan/{ready => done}/brief.md (100%) rename plan/{ready => done}/task.md (93%) diff --git a/HdrHistogram/Utilities/Bitwise.cs b/HdrHistogram/Utilities/Bitwise.cs index 2e45e76..1cd8166 100644 --- a/HdrHistogram/Utilities/Bitwise.cs +++ b/HdrHistogram/Utilities/Bitwise.cs @@ -50,7 +50,7 @@ private static int IntrinsicNumberOfLeadingZeros(long value) //http://graphics.stanford.edu/~seander/bithacks.html#IntegerLogObvious /// - /// Imperative implementation of the LeadingZeroCount, when access to the is not available. + /// Imperative implementation of the LeadingZeroCount, when access to the System.Numerics.BitOperations.LeadingZeroCount(ulong) is not available. /// public static class Imperative { diff --git a/plan/ready/brief.md b/plan/done/brief.md similarity index 100% rename from plan/ready/brief.md rename to plan/done/brief.md diff --git a/plan/ready/task.md b/plan/done/task.md similarity index 93% rename from plan/ready/task.md rename to plan/done/task.md index 4d5b042..7993784 100644 --- a/plan/ready/task.md +++ b/plan/done/task.md @@ -12,7 +12,7 @@ The fix is a one-line doc-comment change; no logic or tests need to change. ### Implementation -- [ ] **Fix XML cref in `HdrHistogram/Utilities/Bitwise.cs:53`** +- [x] **Fix XML cref in `HdrHistogram/Utilities/Bitwise.cs:53`** - **File:** `HdrHistogram/Utilities/Bitwise.cs` - **Line:** 53 (the `` of the `Imperative` nested class) - **Change:** Replace `` with `System.Numerics.BitOperations.LeadingZeroCount(ulong)` @@ -23,12 +23,12 @@ The fix is a one-line doc-comment change; no logic or tests need to change. ### Build Verification -- [ ] **Build for `netstandard2.0` with CS1574 treated as error** +- [x] **Build for `netstandard2.0` with CS1574 treated as error** - **Command:** `dotnet build HdrHistogram/HdrHistogram.csproj -f netstandard2.0 /warnaserror:CS1574` - **Why:** Directly validates acceptance criterion 1 — no `CS1574` warning on the `netstandard2.0` target. - **Verify:** Command exits with code 0 and no `CS1574` diagnostic appears in output. -- [ ] **Build for `net8.0`** +- [x] **Build for `net8.0`** - **Command:** `dotnet build HdrHistogram/HdrHistogram.csproj -f net8.0` - **Why:** Validates acceptance criterion 2 — the fix must not introduce new warnings or errors on the modern target framework. - **Verify:** Command exits with code 0; output contains no new warnings or errors compared to pre-fix baseline. @@ -37,7 +37,7 @@ The fix is a one-line doc-comment change; no logic or tests need to change. ### Regression Testing -- [ ] **Run the full test suite** +- [x] **Run the full test suite** - **Command:** `dotnet test` - **Why:** Confirms no regressions from the doc-comment change (the fix is IL-invisible, but CI must stay green). - **Verify:** All tests pass; no test failures or errors reported. From 63edbf5f2a453c430a3630a5a4d6331e569c50a9 Mon Sep 17 00:00:00 2001 From: leecampbell-codeagent Date: Sun, 1 Mar 2026 09:18:29 +0000 Subject: [PATCH 5/5] feat(#106): complete implementation --- plan/done/brief.md | 48 ----------------------------------------- plan/done/task.md | 54 ---------------------------------------------- 2 files changed, 102 deletions(-) delete mode 100644 plan/done/brief.md delete mode 100644 plan/done/task.md diff --git a/plan/done/brief.md b/plan/done/brief.md deleted file mode 100644 index f8075e8..0000000 --- a/plan/done/brief.md +++ /dev/null @@ -1,48 +0,0 @@ -# Issue #106: Fix Unresolved XML cref in Bitwise.cs for netstandard2.0 - -## Summary - -The build produces a `CS1574` warning when compiling `HdrHistogram.csproj` for the `netstandard2.0` target. -The XML doc comment on the `Imperative` nested class inside `HdrHistogram/Utilities/Bitwise.cs` (line 53) contains a `` reference. -`System.Numerics.BitOperations` was introduced in .NET Core 3.0 and is not part of the `netstandard2.0` API surface, so the compiler cannot resolve the `cref` and emits a warning. - -The fix is to change the XML doc comment so the reference is expressed as plain formatted code (using ``) rather than a resolvable `cref`, eliminating the warning for all target frameworks without altering runtime behaviour. - -## Affected Files - -- `HdrHistogram/Utilities/Bitwise.cs` — line 53, XML `` doc comment on the `Imperative` class (the only change required) - -## What Needs to Change and Why - -| Location | Current | Problem | -|----------|---------|---------| -| `Bitwise.cs:53` | `` | `System.Numerics.BitOperations` does not exist in `netstandard2.0`; compiler emits `CS1574` | - -Replace the `` with `System.Numerics.BitOperations.LeadingZeroCount(ulong)`. -This preserves the intent (showing the fully-qualified method name in a monospace code style) without requiring the compiler to resolve a type that is absent from the `netstandard2.0` reference assembly set. - -No conditional compilation (`#if`) is needed; plain `` is the minimal, least-intrusive change. - -## Acceptance Criteria - -- Building `HdrHistogram.csproj` with `dotnet build -f netstandard2.0` produces **no** `CS1574` warning. -- Building `HdrHistogram.csproj` with `dotnet build -f net8.0` continues to succeed without new warnings. -- The generated XML documentation for `Imperative` still describes its purpose clearly. -- No runtime behaviour changes (the fix is doc-comment only). - -## Test Strategy - -The issue is confined to an XML doc comment; no logic changes, so no new unit tests are required. -Verification is via the build itself: - -1. Run `dotnet build HdrHistogram/HdrHistogram.csproj -f netstandard2.0 /warnaserror:CS1574` — must exit 0. -2. Run `dotnet build HdrHistogram/HdrHistogram.csproj -f net8.0` — must exit 0. -3. Run the existing test suite (`dotnet test`) to confirm no regressions. - -## Risks and Open Questions - -- **Minimal risk**: The change is one line inside a doc comment; it cannot affect compiled IL or runtime behaviour. -- **Open question**: Should `CS1574` be promoted to an error in the project file (`` or `CS1574`) to prevent recurrence? - This would be a separate, optional hardening step and is out of scope for this issue. -- **Alternative considered**: Using `#if NET5_0_OR_GREATER` ... `#else` conditional compilation around the entire `` block. - This works but is significantly more verbose for no additional benefit over a simple `` tag. diff --git a/plan/done/task.md b/plan/done/task.md deleted file mode 100644 index 7993784..0000000 --- a/plan/done/task.md +++ /dev/null @@ -1,54 +0,0 @@ -# Task List: Fix Unresolved XML cref in Bitwise.cs (#106) - -## Context - -`HdrHistogram/Utilities/Bitwise.cs` line 53 has an XML doc `` on the `Imperative` nested class summary. -`System.Numerics.BitOperations` does not exist in `netstandard2.0`, so the compiler emits a `CS1574` warning for that target framework. -The fix is a one-line doc-comment change; no logic or tests need to change. - ---- - -## Tasks - -### Implementation - -- [x] **Fix XML cref in `HdrHistogram/Utilities/Bitwise.cs:53`** - - **File:** `HdrHistogram/Utilities/Bitwise.cs` - - **Line:** 53 (the `` of the `Imperative` nested class) - - **Change:** Replace `` with `System.Numerics.BitOperations.LeadingZeroCount(ulong)` - - **Why:** `System.Numerics.BitOperations` is not part of the `netstandard2.0` API surface; using `` renders the method name in monospace without requiring compiler resolution. - - **Verify:** The word `cref` no longer appears in that `` block; the method name is still present as formatted code. - ---- - -### Build Verification - -- [x] **Build for `netstandard2.0` with CS1574 treated as error** - - **Command:** `dotnet build HdrHistogram/HdrHistogram.csproj -f netstandard2.0 /warnaserror:CS1574` - - **Why:** Directly validates acceptance criterion 1 — no `CS1574` warning on the `netstandard2.0` target. - - **Verify:** Command exits with code 0 and no `CS1574` diagnostic appears in output. - -- [x] **Build for `net8.0`** - - **Command:** `dotnet build HdrHistogram/HdrHistogram.csproj -f net8.0` - - **Why:** Validates acceptance criterion 2 — the fix must not introduce new warnings or errors on the modern target framework. - - **Verify:** Command exits with code 0; output contains no new warnings or errors compared to pre-fix baseline. - ---- - -### Regression Testing - -- [x] **Run the full test suite** - - **Command:** `dotnet test` - - **Why:** Confirms no regressions from the doc-comment change (the fix is IL-invisible, but CI must stay green). - - **Verify:** All tests pass; no test failures or errors reported. - ---- - -## Acceptance Criteria Cross-Reference - -| Acceptance Criterion (from brief) | Covered by Task | -|-----------------------------------|-----------------| -| `dotnet build -f netstandard2.0` produces no `CS1574` warning | Build for `netstandard2.0` with CS1574 treated as error | -| `dotnet build -f net8.0` continues to succeed without new warnings | Build for `net8.0` | -| Generated XML documentation for `Imperative` still describes its purpose clearly | Fix XML cref (method name retained as `` text) | -| No runtime behaviour changes | Fix XML cref (doc-comment only; no IL change) + full test suite |