API usability polish: clearer errors + editor tab-completion (5 additive fixes)#212
Open
HanSur94 wants to merge 5 commits into
Open
API usability polish: clearer errors + editor tab-completion (5 additive fixes)#212HanSur94 wants to merge 5 commits into
HanSur94 wants to merge 5 commits into
Conversation
Backward-compatible, additive: only the error message text changes — the
'DashboardEngine:unknownType' error ID and all behavior are unchanged.
addWidget('linechart', ...) previously threw the dead-end
"Unknown widget type: linechart" with no list of valid types and no
pointer to find them, on the #1 dashboard-building entry point. It now
enumerates the registered types (from DashboardWidgetRegistry.types(),
the single source of truth, so custom-registered types appear too) and
points to DashboardEngine.widgetTypes() — matching the same method's
existing "Valid options: %s" message for unknown name-value keys.
Proven: 18/18 pass across TestDashboardEngineWidgetTypes +
TestDashboardWidgetRegistry (incl. the unknownType-ID assertion); valid
adds and the 'kpi' deprecation alias still work.
Also adds the API-usability audit report (docs/.api-usability/) marking
this finding resolved and recording the next-worst additive finding.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Backward-compatible, additive: only error-message text changes — every '<Class>:unknownOption' error ID, signature, and behavior is unchanged, and no test asserts message text (all assert the ID). All six Tag constructors (Tag base, SensorTag, StateTag, MonitorTag, CompositeTag, DerivedTag) previously threw a bare "Unknown option 'X'." (DerivedTag: "Unknown NV key 'X'.") with no list of valid keys — so a user mistyping 'Unit' for 'Units' got no hint of the correct spelling. This contradicted the project's own convention and was the last spot inconsistent with DashboardEngine's "Valid options: %s" message. Each unknown-option error now appends "Valid options: %s", built via strjoin from the key arrays already local to each splitArgs_ (so the list cannot drift from what the constructor actually accepts). The unreachable defensive 'otherwise' branches at MonitorTag/DerivedTag are left untouched. DerivedTag's wording is normalized to "Unknown option" to match its siblings. Proven: 156/156 pass across TestTag, TestSensorTag, TestStateTag, TestMonitorTag, TestCompositeTag, TestDerivedTag (incl. every unknownOption ID assertion); before/after reproduced for all five concrete subclasses. Resolves audit finding F-2. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…aded Backward-compatible, additive: these four methods previously discarded misspelled/unknown name-value options silently (no error, no warning unless Verbose), so addThreshold(5, 'Colour', 'r') styled nothing and said nothing. That violated the project's own house convention — the FastSense constructor rejects unknown keys immediately "rather than silently discarding them" — and was inconsistent with addLine, which already errors on unknown keys. Each method now calls a new private helper warnUnknownOpts_ that WARNS (does not error) for each unrecognized option, naming the method and listing the valid options. A warning, not an error, was chosen so existing scripts keep working unchanged — they already ignored the option; now the mistake is merely visible. addFill is untouched: it legitimately forwards its extra options to addShaded. Proven: all four typos now warn with a helpful message; 0 false positives on valid + case-insensitive option calls; 48/48 pass across TestAddThreshold, TestAddBand, TestAddMarker, TestAddShaded, TestThresholdLabels, TestRender, plus 5/5 flat add-* function tests. Resolves audit finding F-5. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Backward-compatible, additive: a new editor-metadata file with zero runtime effect — MATLAB reads it only for code completion, and Octave ignores it. No existing signature, behavior, or serialization changes. Adds libs/FastSense/functionSignatures.json covering the core plotting surface — the FastSense constructor plus addLine, addThreshold, addBand, addMarker, addShaded, setScale — with enumerated `choices` for the discrete options (Direction upper/lower, XScale/YScale linear/log, DownsampleMethod minmax/lttb, Marker, LineStyle). The editor now suggests valid option names and values as the user types, directly mitigating the option-typo friction. Proven: validateFunctionSignaturesJSON returns 0 messages (schema-valid; all method and type names resolve against the real class metadata with FastSense on the path); a runtime smoke (construct + add* + setScale) is clean with no error or warning; no .m files changed so existing tests and examples are inherently unaffected. Resolves audit finding F-3 for the FastSense scope (Dashboard/Tag signatures are queued follow-ups). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…letion
Backward-compatible, additive: a new editor-metadata file with zero
runtime effect — MATLAB reads it only for code completion, Octave
ignores it. No existing signature, behavior, or serialization changes.
Adds libs/Dashboard/functionSignatures.json covering the DashboardEngine
constructor (Name + Theme/LiveInterval/InfoFile/ProgressMode/
ShowTimePanel) and addWidget. The addWidget `type` argument is modeled
as a `choices` enum of all 19 built-in widget types, so the editor now
suggests the valid types as the user types — surfacing the same list the
run-1 unknown-type error lists, but at the point of entry. Common
options (Position, Title, Tag, Label) are offered too.
Proven: validateFunctionSignaturesJSON returns 0 messages (schema-valid;
the optional positional Name uses the R2025b-required "ordered" kind, not
the deprecated "optional"); runtime smoke confirms addWidget('number')
still returns a NumberWidget and an unknown type still errors
DashboardEngine:unknownType — the file is runtime-inert. No .m changed,
so existing tests and examples are unaffected. Resolves audit finding
F-3b.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
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
1 participant
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.
Five small, backward-compatible, additive API-usability fixes from
/loop /api-polish. Every change is either a better error message, a non-fatal warning, or a new editor-metadata file — no public signature, default behavior, property name, or serialization key is changed, so existing dashboard scripts and serialized dashboards keep working unchanged.Each fix was reproduced ("before"), made minimally, and proven both directions (existing tests pass + the friction is gone) in headless MATLAB R2025b.
What's in here
02909675DashboardEngine.addWidgetunknown-type error now lists all valid widget types + points towidgetTypes()(was a dead-endUnknown widget type: x). List derived fromDashboardWidgetRegistry.types().TestDashboardEngineWidgetTypes+TestDashboardWidgetRegistry80f2b44cTag,SensorTag,StateTag,MonitorTag,CompositeTag,DerivedTag) now list valid name-value keys in theirunknownOptionerrors (was a bareUnknown option 'x'.).fed93842FastSense.addThreshold/addBand/addMarker/addShadednow warn on unknown options instead of silently swallowing typos — aligning with the constructor's house convention. Warning (not error) keeps scripts running.TestAdd{Threshold,Band,Marker,Shaded}+TestThresholdLabels+TestRender, 5/5 flat tests, 0 false positives on valid calls8d7af2celibs/FastSense/functionSignatures.json— editor tab-completion for theFastSenseconstructor +add*+setScale, withchoicesenums (Direction, scales, downsample method, …).validateFunctionSignaturesJSON→ 0 messages; runtime smoke clean90d0579flibs/Dashboard/functionSignatures.json— tab-completion for theDashboardEngineconstructor +addWidget, with thetypearg as achoicesenum of all 19 widget types.validateFunctionSignaturesJSON→ 0 messages; runtime smoke cleanFixes 1–3 close the loop on a single theme: never let a mistyped option fail silently or dead-end. Fixes 4–5 prevent the typo at the source via editor completion.
Why backward-compatible
*:unknownType/*:unknownOptionIDs are unchanged, and no test asserts message text (all assert the ID).addFillis untouched (it legitimately forwards extras toaddShaded). Erroring would have been breaking and is left as a future major-version option.Notes
docs/.api-usability/audit-2026-06-24.md(records each finding, the before/after, and the next-worst additive target — F-3c, Tag-constructor signatures).🤖 Generated with Claude Code