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,12 +36,12 @@ public enum MqttWriteEncodeError
/// <summary>
/// Encodes an outbound MQTT write — the payload bytes and the topic to publish them on — for both
/// ingest shapes (Gitea #508). Pure: no I/O, no transport, no clock beyond the Sparkplug command
/// ingest shapes. Pure: no I/O, no transport, no clock beyond the Sparkplug command
/// timestamp, so the whole encode contract is unit-testable without a broker.
/// </summary>
/// <remarks>
/// <para>
/// <b>A missing write destination is a refusal, never a no-op.</b> Before #508 the driver
/// <b>A missing write destination is a refusal, never a no-op.</b> Previously the driver
/// implemented no <c>IWritable</c> at all, so every MQTT node materialised read-only — honest, if
/// limited. The one outcome that would be strictly worse is a node that <em>looks</em> writable,
/// accepts a write, returns Good and publishes nothing. So a Plain tag with no <c>writeTopic</c>
@@ -81,7 +81,7 @@ public static class MqttWriteEncoder
public const int WriteQos = 0;
/// <summary>
/// QoS for a Plain-mode <c>writeTopic</c> publish (STAB-26). At QoS 1 the publish completes only
/// QoS for a Plain-mode <c>writeTopic</c> publish. At QoS 1 the publish completes only
/// once the broker has PUBACKed (or refused) it, so a Good write status means "the broker accepted
/// the message" rather than "the bytes left this socket"; at QoS 0 a broker-side refusal or a
/// connection that dropped under the send was indistinguishable from success.
@@ -96,7 +96,7 @@ public static class MqttWriteEncoder
/// <param name="value">The value to write.</param>
/// <param name="encoded">The topic + payload to publish, when this returns <see cref="MqttWriteEncodeError.None"/>.</param>
/// <param name="effectiveDataType">
/// Sparkplug only (STAB-25): the type to encode the metric as when the tag did not author one — the
/// Sparkplug only: the type to encode the metric as when the tag did not author one — the
/// type the metric's live birth certificate declared, the same <c>authored ? authored : birth</c>
/// precedence the ingest path coerces reads with. <see langword="null"/> encodes as
/// <see cref="MqttTagDefinition.DataType"/>, which for an unauthored tag is only the record's