docs(comments): strip internal task/milestone/bundle bookkeeping from code comments
Remove project bookkeeping citations from shipped code comments across the solution: hyphenated task IDs (WP-14, StoreAndForward-025), milestone/task/ issue refs (M3, Task 4, Audit Log #23, #21), Bundle X task-bundle labels, and C/D/K/S/T phase labels. Comment text only — no code logic, string/log literals, or XML-doc structure changed. Genuine descriptions are preserved (only the citation is stripped), and technical lookalikes are retained (UTF-8, SHA-256, T00:00:00, M365, UTC-5, pre-C4/pre-C5 schema versions). Flagged by the new CommentChecker TaskReferenceInComment / TrackingReferenceInComment checks plus targeted grep passes; full solution builds clean, append-only guard tests pass.
This commit is contained in:
Joseph Doherty
@@ -5,11 +5,11 @@ using ZB.MOM.WW.ScadaBridge.Commons.Types;
|
||||
namespace ZB.MOM.WW.ScadaBridge.InboundAPI;
|
||||
|
||||
/// <summary>
|
||||
/// WP-4: Route.To() helper for cross-site calls from inbound API scripts.
|
||||
/// Route.To() helper for cross-site calls from inbound API scripts.
|
||||
/// Resolves instance to site, routes via <see cref="IInstanceRouter"/>, blocks until
|
||||
/// response or timeout. Site unreachable returns error (no store-and-forward).
|
||||
///
|
||||
/// InboundAPI-016: the helper carries the executing method's <see cref="CancellationToken"/>
|
||||
/// The helper carries the executing method's <see cref="CancellationToken"/>
|
||||
/// (the method-level timeout). Routed calls inherit that deadline by default, so a
|
||||
/// natural script — <c>Route.To("inst").Call("doWork", p)</c> — is timeout-bounded
|
||||
/// without the script having to thread a token explicitly.
|
||||
@@ -49,7 +49,7 @@ public class RouteHelper
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// InboundAPI-016: returns a <see cref="RouteHelper"/> whose routed calls inherit
|
||||
/// Returns a <see cref="RouteHelper"/> whose routed calls inherit
|
||||
/// <paramref name="deadlineToken"/> (the executing method's timeout) by default.
|
||||
/// <see cref="InboundScriptExecutor"/> calls this when it builds the script
|
||||
/// context so the method timeout actually covers routed calls, as the design doc
|
||||
@@ -61,7 +61,7 @@ public class RouteHelper
|
||||
new(_instanceLocator, _instanceRouter, deadlineToken, _requestAbortedToken, _parentExecutionId);
|
||||
|
||||
/// <summary>
|
||||
/// InboundAPI-029: returns a <see cref="RouteHelper"/> carrying the raw request-abort
|
||||
/// Returns a <see cref="RouteHelper"/> carrying the raw request-abort
|
||||
/// token (a client disconnect) <em>separately</em> from the method deadline. Most
|
||||
/// routed calls remain bounded by the method deadline (which already incorporates the
|
||||
/// abort), but <see cref="RouteTarget.WaitForAttribute"/> uses this token so its wait
|
||||
@@ -74,7 +74,7 @@ public class RouteHelper
|
||||
new(_instanceLocator, _instanceRouter, _deadlineToken, requestAbortedToken, _parentExecutionId);
|
||||
|
||||
/// <summary>
|
||||
/// Audit Log #23 (ParentExecutionId): returns a <see cref="RouteHelper"/> whose
|
||||
/// Audit Log (ParentExecutionId): returns a <see cref="RouteHelper"/> whose
|
||||
/// routed <see cref="RouteTarget.Call"/> requests carry
|
||||
/// <paramref name="parentExecutionId"/> as <see cref="RouteToCallRequest.ParentExecutionId"/>.
|
||||
/// For an inbound API request this is the inbound request's own per-request
|
||||
@@ -100,7 +100,7 @@ public class RouteHelper
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// WP-4: Represents a route target (an instance) for cross-site calls.
|
||||
/// Represents a route target (an instance) for cross-site calls.
|
||||
/// </summary>
|
||||
public class RouteTarget
|
||||
{
|
||||
@@ -118,7 +118,7 @@ public class RouteTarget
|
||||
/// <param name="instanceLocator">Service to resolve the site id for the instance.</param>
|
||||
/// <param name="instanceRouter">Service to route cross-site calls.</param>
|
||||
/// <param name="deadlineToken">Cancellation token representing the method-level deadline.</param>
|
||||
/// <param name="requestAbortedToken">Raw client-disconnect token, independent of the method timeout (InboundAPI-029).</param>
|
||||
/// <param name="requestAbortedToken">Raw client-disconnect token, independent of the method timeout.</param>
|
||||
/// <param name="parentExecutionId">Optional parent execution id for audit correlation on routed calls.</param>
|
||||
internal RouteTarget(
|
||||
string instanceCode,
|
||||
@@ -141,7 +141,7 @@ public class RouteTarget
|
||||
/// perspective. <paramref name="parameters"/> may be a dictionary or an
|
||||
/// anonymous object (<c>new { name = "Bob" }</c>) — see <see cref="ScriptArgs"/>.
|
||||
///
|
||||
/// InboundAPI-016: when <paramref name="cancellationToken"/> is not supplied the
|
||||
/// When <paramref name="cancellationToken"/> is not supplied the
|
||||
/// routed call inherits the executing method's timeout, so the call is bounded by
|
||||
/// the method-level deadline with no token argument.
|
||||
/// </summary>
|
||||
@@ -158,7 +158,7 @@ public class RouteTarget
|
||||
var siteId = await ResolveSiteAsync(token);
|
||||
var correlationId = Guid.NewGuid().ToString();
|
||||
|
||||
// Audit Log #23 (ParentExecutionId): stamp the spawning execution's id
|
||||
// Audit Log (ParentExecutionId): stamp the spawning execution's id
|
||||
// (the inbound API request's ExecutionId) so the routed site script
|
||||
// records this call's parent. CorrelationId above is a separate concern
|
||||
// — the per-operation lifecycle id, freshly minted per routed call.
|
||||
@@ -205,7 +205,7 @@ public class RouteTarget
|
||||
var siteId = await ResolveSiteAsync(token);
|
||||
var correlationId = Guid.NewGuid().ToString();
|
||||
|
||||
// Audit Log #23 (ParentExecutionId): mirrors the Call path — stamp the
|
||||
// Audit Log (ParentExecutionId): mirrors the Call path — stamp the
|
||||
// spawning inbound request's ExecutionId so future site-side audit
|
||||
// emission for routed reads can record this read's parent. Symmetric
|
||||
// with RouteToCallRequest so script authors get the same correlation
|
||||
@@ -233,8 +233,8 @@ public class RouteTarget
|
||||
/// comparison.
|
||||
///
|
||||
/// <para>
|
||||
/// InboundAPI-029: unlike the other routed calls (which inherit the method deadline
|
||||
/// per InboundAPI-016), the wait is bounded by <paramref name="timeout"/> — the WAIT
|
||||
/// Unlike the other routed calls (which inherit the method deadline
|
||||
/// by default), the wait is bounded by <paramref name="timeout"/> — the WAIT
|
||||
/// timeout — NOT the generic method deadline. The SITE enforces <paramref name="timeout"/>
|
||||
/// and returns <c>Matched=false</c> when it elapses; the local token is built from a
|
||||
/// per-wait CTS (the wait timeout plus a small grace), an explicit caller token, and
|
||||
@@ -254,12 +254,12 @@ public class RouteTarget
|
||||
TimeSpan timeout,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
// InboundAPI-031: do NOT impose a local wait-timeout backstop here. The site
|
||||
// Do NOT impose a local wait-timeout backstop here. The site
|
||||
// enforces the wait `timeout` and returns Matched=false when it elapses, and the
|
||||
// cluster Ask in CommunicationService.RouteToWaitForAttributeAsync already bounds
|
||||
// the round trip by `timeout + IntegrationTimeout` — the authoritative backstop
|
||||
// for a missing site response. A local CTS of `timeout + small grace` (the prior
|
||||
// InboundAPI-029 approach) was TIGHTER than that round-trip budget, so a
|
||||
// approach) was TIGHTER than that round-trip budget, so a
|
||||
// slow-but-valid timed-out response could be cancelled into an exception instead
|
||||
// of the spec-mandated `false`. Link ONLY the client-disconnect token and an
|
||||
// explicit caller token — NOT the method deadline — so a client abort still
|
||||
@@ -269,7 +269,7 @@ public class RouteTarget
|
||||
var token = linked.Token;
|
||||
var siteId = await ResolveSiteAsync(token);
|
||||
|
||||
// Audit Log #23 (ParentExecutionId): mirrors the Call path — stamp the
|
||||
// Audit Log (ParentExecutionId): mirrors the Call path — stamp the
|
||||
// spawning inbound request's ExecutionId so future site-side audit
|
||||
// emission for routed waits can record this wait's parent. CorrelationId
|
||||
// is the per-operation lifecycle id, freshly minted per routed wait.
|
||||
@@ -320,7 +320,7 @@ public class RouteTarget
|
||||
var siteId = await ResolveSiteAsync(token);
|
||||
var correlationId = Guid.NewGuid().ToString();
|
||||
|
||||
// Audit Log #23 (ParentExecutionId): mirrors the Call path — stamp the
|
||||
// Audit Log (ParentExecutionId): mirrors the Call path — stamp the
|
||||
// spawning inbound request's ExecutionId so future site-side audit
|
||||
// emission for routed writes can record this write's parent. Symmetric
|
||||
// with RouteToCallRequest so script authors get the same correlation
|
||||
@@ -339,7 +339,7 @@ public class RouteTarget
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// InboundAPI-016: a routed call with no explicit token inherits the executing
|
||||
/// A routed call with no explicit token inherits the executing
|
||||
/// method's deadline. An explicitly supplied token (for a tighter bound) wins.
|
||||
/// </summary>
|
||||
private CancellationToken Effective(CancellationToken explicitToken) =>
|
||||
|
||||
Reference in New Issue
Block a user