docs(src): add missing XML docs and strip tracking-ID comments

Sweep of 203 source files resolving CommentChecker findings: add
<summary>/<param>/<returns>/<inheritdoc> where missing, and remove
resolved task/issue tracking markers (Tests-NNN, Worker-NNN, Server-NNN,
Task N) from code comments. Comment/doc-only — no logic changes.
Server+Tests build clean under TreatWarningsAsErrors.
This commit is contained in:
Joseph Doherty
2026-07-07 14:09:49 -04:00
parent 8914472706
commit fca978de07
203 changed files with 1834 additions and 1383 deletions
@@ -16,6 +16,7 @@ namespace ZB.MOM.WW.MxGateway.Tests.Security.Authorization;
public sealed class ConstraintEnforcerTests
{
/// <summary>Verifies that read outside allowed subtree returns failure.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CheckReadTagAsync_WhenOutsideReadSubtree_ReturnsFailure()
{
@@ -35,6 +36,7 @@ public sealed class ConstraintEnforcerTests
}
/// <summary>Verifies that write with high classification returns failure and audits.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CheckWriteHandleAsync_WhenClassificationTooHigh_ReturnsFailureAndAudits()
{
@@ -84,6 +86,7 @@ public sealed class ConstraintEnforcerTests
}
/// <summary>A denial carrying a parseable correlation id stores it on the audit record.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RecordDenialAsync_WithGuidCorrelationId_StoresCorrelationId()
{
@@ -106,6 +109,7 @@ public sealed class ConstraintEnforcerTests
/// A denial with a non-GUID correlation id leaves the typed audit correlation id null but
/// still preserves the raw client correlation id in DetailsJson so it is not lost.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RecordDenialAsync_WithNonGuidCorrelationId_LeavesCorrelationIdNullButPreservesRawInDetails()
{
@@ -130,6 +134,7 @@ public sealed class ConstraintEnforcerTests
}
/// <summary>A denial with no identity records the canonical "anonymous" actor.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task RecordDenialAsync_WithoutIdentity_UsesAnonymousActor()
{
@@ -150,6 +155,7 @@ public sealed class ConstraintEnforcerTests
}
/// <summary>Verifies that historized-only constraint requires historized attribute.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CheckReadTagAsync_WithHistorizedOnly_RequiresRequestedAttributeToBeHistorized()
{
@@ -169,6 +175,7 @@ public sealed class ConstraintEnforcerTests
}
/// <summary>Verifies that alarm-only constraint requires alarm attribute.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CheckReadTagAsync_WithAlarmOnly_RequiresRequestedAttributeToBeAlarm()
{
@@ -188,6 +195,7 @@ public sealed class ConstraintEnforcerTests
}
/// <summary>Verifies that attribute-only constraint fails closed for object tag.</summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CheckReadTagAsync_WithAttributeOnlyConstraint_FailsClosedForObjectTag()
{
@@ -212,6 +220,7 @@ public sealed class ConstraintEnforcerTests
/// Without the <c>[]</c> fallback in ResolveTarget the bare name misses the index and a
/// read-constrained key gets a spurious tag_metadata denial for an AddItem it should allow.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CheckReadTagAsync_WithBareArrayName_ResolvesViaArraySuffixFallback()
{
@@ -236,6 +245,7 @@ public sealed class ConstraintEnforcerTests
/// A bare non-array name that is genuinely absent from the index still resolves to null:
/// the <c>[]</c> probe must not manufacture a false positive for a scalar/missing tag.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CheckReadTagAsync_WithMissingNonArrayName_StillFailsToResolve()
{
@@ -265,8 +275,9 @@ public sealed class ConstraintEnforcerTests
/// <summary>
/// The <c>[]</c>-suffix fallback widened *resolution* of a bare array name, not *authorization*:
/// a bare array attribute that resolves through the fallback but is outside the key's read scope
/// must still be denied with a <c>read_scope</c> failure (Server-058).
/// must still be denied with a <c>read_scope</c> failure.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CheckReadTagAsync_WithBareArrayName_OutOfScope_StillDeniedReadScope()
{
@@ -289,8 +300,9 @@ public sealed class ConstraintEnforcerTests
/// <summary>
/// A write against an array handle whose registration carries the suffixed form ("Pump_001.Levels[]")
/// resolves through <c>ResolveTarget</c> and is denied with a <c>write_scope</c> failure when the
/// array attribute is outside the key's write scope (Server-058).
/// array attribute is outside the key's write scope.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CheckWriteHandleAsync_WithSuffixedArrayRegistration_OutOfScope_StillDeniedWriteScope()
{
@@ -331,9 +343,9 @@ public sealed class ConstraintEnforcerTests
/// <summary>
/// A write against an in-scope array handle whose registration carries the suffixed form is still
/// denied when the array attribute's <c>SecurityClassification</c> exceeds the key's
/// <c>MaxWriteClassification</c>, resolved through <c>ResolveTarget</c> via the suffixed address
/// (Server-058).
/// <c>MaxWriteClassification</c>, resolved through <c>ResolveTarget</c> via the suffixed address.
/// </summary>
/// <returns>A task that represents the asynchronous operation.</returns>
[Fact]
public async Task CheckWriteHandleAsync_WithSuffixedArrayRegistration_ClassificationTooHigh_StillDenied()
{
@@ -490,10 +502,14 @@ public sealed class ConstraintEnforcerTests
/// <summary>Gets the current cache entry.</summary>
public GalaxyHierarchyCacheEntry Current { get; } = current;
/// <inheritdoc />
/// <summary>No-op refresh; the stub's <see cref="Current"/> entry never changes.</summary>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public Task RefreshAsync(CancellationToken cancellationToken) => Task.CompletedTask;
/// <inheritdoc />
/// <summary>No-op wait; the stub's <see cref="Current"/> entry is already loaded.</summary>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public Task WaitForFirstLoadAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}
@@ -502,7 +518,10 @@ public sealed class ConstraintEnforcerTests
/// <summary>Gets the recorded canonical audit events.</summary>
public List<AuditEvent> Events { get; } = [];
/// <inheritdoc />
/// <summary>Records the audit event in <see cref="Events"/> for later assertions.</summary>
/// <param name="auditEvent">The audit event to record.</param>
/// <param name="cancellationToken">Token to cancel the asynchronous operation.</param>
/// <returns>A task that represents the asynchronous operation.</returns>
public Task WriteAsync(AuditEvent auditEvent, CancellationToken cancellationToken = default)
{
Events.Add(auditEvent);