Trim the README to what a consumer needs to get started - #31
Merged
Merged
Conversation
It had grown into a reference: the `.slx`/`.mdl` part-layout matrix across both eras, which release stopped recording a model UUID, the `(BlockType, parameter)` menu-versus-expression rules. All of that is documented where it is measured — `test/parity/matlab/README.md` for the layouts, the tables themselves for the parameters — so the README now points there instead of restating it, and cannot drift out of step with it. What replaces it is the part that was missing: how the one real consumer actually consumes this. The old opening example was `createSession` plus `ingest`/`toDTO`/`loadFromPath`, none of which the VS Code extension calls at all; it parses and hands the result to the `DataModel` session, and asks about a folder through `buildUsageIndex`. Those two are now the two examples, and both were run against `test/fixtures/` before being written down — `getDataSourceIds()` really does answer `['params.sldd', 'a.slx']` there. `createSession` and the Node subpath stay as the one-liners they should always have been. Kept in full: the four things a consumer cannot guess and will get wrong without being told — that a block is addressed by SID because a name is unique only within its system, the MATLAB shadowing order, that `linkTarget: ''` is an answer rather than an absence, and that an unreadable file contributes nothing instead of failing the set. Also states what was only tribal knowledge: releases are tags, `dist/` is committed so an install needs no build step, the barrel is the whole supported surface, and host changes land here before the extension moves its pin.
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.
Docs only — no source, no version bump, no tag.
The README had grown into a reference: the part-layout matrix for both
.slx/.mdleras, which release stopped recording a model UUID, the(BlockType, parameter)menu-versus-expression rules. That detail is documented where it is measured —test/parity/matlab/README.mdfor the layouts, the tables themselves for the parameters — so the README points there now instead of restating it, and cannot drift out of step with it.In its place is what was missing: how the one real consumer consumes this. The old opening example was
createSessionplusingest/toDTO/loadFromPath— none of which the VS Code extension calls. It parses and hands the result to theDataModelsession, and asks about a folder throughbuildUsageIndex. Those are now the two examples, and both were executed againsttest/fixtures/before being written down (getDataSourceIds()really does answer['params.sldd', 'a.slx']there;editProperty/undo/usagesOf/paramsOfall resolve).Kept in full — the four things a consumer cannot guess: SID addressing, the MATLAB shadowing order,
linkTarget: ''being an answer rather than an absence, and an unreadable file contributing nothing instead of failing the set.Newly stated, having been tribal knowledge: releases are tags,
dist/is committed so installing needs no build step, the barrel is the whole supported surface, and host changes land here before the extension moves its pin.147 lines to 118.