Skip to content

docs: give the four param-only constructors a summary - #1924

Merged
laurentiu021 merged 1 commit into
mainfrom
docs/audio-row-ctor-summary
Aug 18, 2026
Merged

docs: give the four param-only constructors a summary#1924
laurentiu021 merged 1 commit into
mainfrom
docs/audio-row-ctor-summary

Conversation

@laurentiu021

Copy link
Copy Markdown
Owner

What raised this

CodeQL alert #1724cs/xmldoc/missing-summary on AudioSessionRowViewModel.cs:104, created when
batch 89 merged. That batch added a <param> block for the new reportFailure callback but no
<summary> above it, so the constructor's doc block documented one argument of a member whose purpose
was never stated.

Severity is note and nothing is broken. It is here because it is a new alert introduced by my own
change, and the standard on this repo is to leave none behind.

Fixed the shape, not the alert

Swept the whole source for the pattern (a doc block that starts at <param> with no <summary> anywhere
above it) and found four constructors, of which CodeQL had reported only two:

Constructor Alert Introduced by
AudioSessionRowViewModel #1724 batch 89 (reportFailure)
DashboardViewModel #1715 (pre-existing) the crashMarkers required-arg change (#1772)
EtaCalculator not reported batch 81 (TimeProvider seam)
EtwBandwidthSource not reported batch 86 (TimeProvider seam)

The two CodeQL missed are the same defect, and both are mine — a grep keyed on the shape found them
where the alert list would have left half a migration behind. Post-change sweep: 0 blocks remaining.

The convention copied is BandwidthMonitorViewModel, whose two constructors already lead with a summary.

Each summary says something the signature does not

Every line was verified against the body rather than guessed:

  • AudioSessionRowViewModel — seeds volume/mute/name/peak through the backing fields, so the
    change handlers never fire and write the value straight back to the service; the same echo suppression
    ApplyUpdate relies on. (Verified: _volume/_isMuted/_displayName/_peakLevel are direct field
    assignments, and the class doc states the ApplyUpdate re-entrancy guard.)
  • EtaCalculator — starts with no samples, so Remaining stays null and the rate stays zero until
    the first Update reports a real advance.
  • EtwBandwidthSource — opens no ETW session; that happens in Start(). Which is precisely why
    the view model can hold one and only pay for the trace if per-process mode is switched on while
    elevated. (Verified: _session has no initializer; new TraceEventSession(...) is inside Start().)
  • DashboardViewModel — starts InitAsync fire-and-forget (previous-crash report, static info,
    drives, activity, health score, then the vitals/temperature/alert loops) and reads elevation once
    because it cannot change without a relaunch.

Not touched, deliberately

The four cs/constant-condition alerts (BandwidthMonitorViewModel:278/470,
ResourceHistoryViewModel:164/190) remain open. They sit on the post-await if (_disposed) return;
guards, which CodeQL reads as constant because it cannot see the field being written from Dispose on
another turn. Removing them would reintroduce the use-after-dispose crashes fixed in batches 35/40.
They are false positives and stay.

Verification

Comments only — zero executable lines changed. All four projects build 0 errors / 0 warnings;
dotnet format --verify-no-changes exit 0; author headers intact on all four files; leak scan over all
32 terms gives 0 hits. docs: so no version bump and no release.

CodeQL raised cs/xmldoc/missing-summary #1724 on AudioSessionRowViewModel's
constructor: batch 89 added a <param> block for the new reportFailure callback
without a <summary> above it, so the whole doc block documented an argument of a
member with no stated purpose.

Swept the source for the shape rather than fixing the one alert, and found FOUR
constructors documented with <param> only — CodeQL had reported just two of them
(#1724 and the pre-existing #1715 on DashboardViewModel). The other two are mine
too: EtaCalculator (batch 81's TimeProvider seam) and EtwBandwidthSource (batch
86's). All four now lead with a summary, matching BandwidthMonitorViewModel, whose
constructors already carry one.

Each summary states something the reader cannot get from the signature and that I
verified against the body: the audio row seeds volume/mute/name/peak through the
backing fields so the change handlers do not echo straight back to the service;
EtaCalculator starts with no samples so Remaining stays null; EtwBandwidthSource
opens no ETW session until Start(), which is why holding one costs nothing and
needs no elevation; DashboardViewModel starts InitAsync fire-and-forget and reads
elevation once because it cannot change without a relaunch.

Comments only — no behaviour change, no version bump, no release.
@laurentiu021
laurentiu021 merged commit 6a249b9 into main Aug 18, 2026
5 checks passed
@laurentiu021
laurentiu021 deleted the docs/audio-row-ctor-summary branch August 18, 2026 13:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant