docs: fill missing XML docs and strip tracking IDs from src comments

Clears CommentChecker findings in src/ (3,280 -> 209, the remainder being false
positives like PLC-5/IEEE-754/M0.0) by adding missing summaries/params/returns,
normalising inheritdoc usage, and removing Gitea/review tracking IDs while keeping
the rationale they annotated. Comment-only: comment-stripped sources are identical
to the parent commit.
This commit is contained in:
Joseph Doherty
2026-10-15 06:14:58 -04:00
parent ebcbd81fca
commit 826312befe
430 changed files with 4434 additions and 3923 deletions
@@ -36,7 +36,7 @@ public static class FocasDriverFactoryExtensions
/// </summary>
/// <param name="registry">The driver factory registry to register with.</param>
/// <param name="loggerFactory">Optional logger factory; without it the driver and its wire client run on
/// the null logger and none of their diagnostics reach the node log (CONV-3).</param>
/// the null logger and none of their diagnostics reach the node log.</param>
public static void Register(DriverFactoryRegistry registry, ILoggerFactory? loggerFactory = null)
{
ArgumentNullException.ThrowIfNull(registry);
@@ -61,7 +61,7 @@ public static class FocasDriverFactoryExtensions
loggerFactory?.CreateLogger<FocasDriver>(),
// Hand the driver the SAME parse it was built with, so InitializeAsync can re-derive EVERY
// config-derived dependency on a reinitialize — options AND the backend client factory
// together (#516). Re-parsing options alone would run a new device/tag set against the old
// together. Re-parsing options alone would run a new device/tag set against the old
// backend, which is worse than not re-parsing at all.
rebind: json => ParseBinding(driverInstanceId, json, loggerFactory));
}
@@ -126,7 +126,7 @@ public static class FocasDriverFactoryExtensions
/// <paramref name="defaultMs"/> for a null / zero / negative value. A non-positive
/// <c>Timeout</c> would make <see cref="SynchronizedFocasClient"/> DISABLE its per-call
/// wall-clock ceiling (falling back to the caller's long-lived poll token), reintroducing the
/// exact unbounded-read-on-a-frozen-peer wedge the S7 R2-01 read-leg fix eliminated. Clamping
/// exact unbounded-read-on-a-frozen-peer wedge the S7 read-leg fix eliminated. Clamping
/// here at the config boundary guarantees the deadline can never be authored away.
/// </summary>
/// <param name="ms">The operator-supplied timeout in milliseconds, or null.</param>
@@ -365,7 +365,7 @@ public static class FocasDriverFactoryExtensions
public TimeSpan? PollInterval { get; init; }
}
/// <summary>Optional <c>PmcCoalesce</c> config section (#266).</summary>
/// <summary>Optional <c>PmcCoalesce</c> config section.</summary>
internal sealed class FocasPmcCoalesceDto
{
/// <summary>Gets or sets a value indicating whether coalescing is on.</summary>
@@ -392,7 +392,7 @@ public static class FocasDriverFactoryExtensions
/// reinitialize adopts all of it atomically.
/// <para>This exists because a partial adoption is a real hazard, not a theoretical one: the driver's
/// <see cref="IFocasClientFactory"/> is chosen by the config's <c>Backend</c> key, so re-parsing
/// <see cref="Options"/> alone would poll a NEW device/tag set through the OLD backend (Gitea #516).</para>
/// <see cref="Options"/> alone would poll a NEW device/tag set through the OLD backend.</para>
/// </summary>
/// <param name="Options">The typed driver options.</param>
/// <param name="ClientFactory">The backend client factory the <c>Backend</c> key selects.</param>