docs: give the four param-only constructors a summary - #1924
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What raised this
CodeQL alert #1724 —
cs/xmldoc/missing-summaryonAudioSessionRowViewModel.cs:104, created whenbatch 89 merged. That batch added a
<param>block for the newreportFailurecallback but no<summary>above it, so the constructor's doc block documented one argument of a member whose purposewas never stated.
Severity is
noteand nothing is broken. It is here because it is a new alert introduced by my ownchange, 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>anywhereabove it) and found four constructors, of which CodeQL had reported only two:
AudioSessionRowViewModelreportFailure)DashboardViewModelcrashMarkersrequired-arg change (#1772)EtaCalculatorTimeProviderseam)EtwBandwidthSourceTimeProviderseam)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 thechange handlers never fire and write the value straight back to the service; the same echo suppression
ApplyUpdaterelies on. (Verified:_volume/_isMuted/_displayName/_peakLevelare direct fieldassignments, and the class doc states the
ApplyUpdatere-entrancy guard.)EtaCalculator— starts with no samples, soRemainingstays null and the rate stays zero untilthe first
Updatereports a real advance.EtwBandwidthSource— opens no ETW session; that happens inStart(). Which is precisely whythe view model can hold one and only pay for the trace if per-process mode is switched on while
elevated. (Verified:
_sessionhas no initializer;new TraceEventSession(...)is insideStart().)DashboardViewModel— startsInitAsyncfire-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-conditionalerts (BandwidthMonitorViewModel:278/470,ResourceHistoryViewModel:164/190) remain open. They sit on the post-awaitif (_disposed) return;guards, which CodeQL reads as constant because it cannot see the field being written from
Disposeonanother 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-changesexit 0; author headers intact on all four files; leak scan over all32 terms gives 0 hits.
docs:so no version bump and no release.