Skip to content

Give an example an apis field, and take the notes away - #208

Closed
abernier wants to merge 1 commit into
eval-baselinefrom
llms-apis-field
Closed

Give an example an apis field, and take the notes away#208
abernier wants to merge 1 commit into
eval-baselinefrom
llms-apis-field

Conversation

@abernier

Copy link
Copy Markdown
Member

The document an agent reads names no technique. aquarium is served with
an empty description and the single tag transmission, while what makes
it work -- useMask and a backside MeshTransmissionMaterial -- is
nowhere, and the reader pays 400 lines of TSX to rediscover it.

Identifiers are data, not prose. Three median-length API names are 34
characters, 28% of the 120 the one-line description gets, which is
exactly why they get their own field rather than eating the sentence.

apis renders in the facts block of <name>.md, next to the tags, and
not in llms.txt: ~34 characters on 167 index lines takes that file from
~19 kB to ~25 kB, on a document read at the start of every question, to
say what is one fetch away once the choice is already made.

Optional for now. It becomes required once every example carries one --
required before it is populated is a red CI on day one.

lint:metadata enforces apis ⊆ imports, as a hard error. The check is
local and only local: whether drei still exports the name at the pinned
version is the bundler's job, and rollup already fails the build on a
missing named export. What no build can catch is metadata drifting away
from the source, and that is what this catches -- drei renames an API,
someone fixes the import, apis still lists the old name, the lint
breaks. That property is why the example's sources are now inputs of
//#lint:metadata: cached past a dropped import, the rule stops catching
the one thing it exists for.

notes goes. Two uses, both the same string, "Updated for
MeshTransmissionMaterial in 2023." -- maintenance history that belongs in
git, rendered into the document where a reader cannot tell it from
documentation. assets[].notes had zero uses and went with it.

Closes #194


Stack created with GitHub Stacks CLIGive Feedback 💬

The document an agent reads names no technique. `aquarium` is served with
an empty description and the single tag `transmission`, while what makes
it work -- `useMask` and a backside `MeshTransmissionMaterial` -- is
nowhere, and the reader pays 400 lines of TSX to rediscover it.

Identifiers are data, not prose. Three median-length API names are 34
characters, 28% of the 120 the one-line `description` gets, which is
exactly why they get their own field rather than eating the sentence.

`apis` renders in the facts block of `<name>.md`, next to the tags, and
not in `llms.txt`: ~34 characters on 167 index lines takes that file from
~19 kB to ~25 kB, on a document read at the start of every question, to
say what is one fetch away once the choice is already made.

Optional for now. It becomes required once every example carries one --
required before it is populated is a red CI on day one.

`lint:metadata` enforces `apis ⊆ imports`, as a hard error. The check is
local and only local: whether drei still exports the name at the pinned
version is the bundler's job, and rollup already fails the build on a
missing named export. What no build can catch is metadata drifting away
from the source, and that is what this catches -- drei renames an API,
someone fixes the import, `apis` still lists the old name, the lint
breaks. That property is why the example's sources are now inputs of
`//#lint:metadata`: cached past a dropped import, the rule stops catching
the one thing it exists for.

`notes` goes. Two uses, both the same string, "Updated for
MeshTransmissionMaterial in 2023." -- maintenance history that belongs in
git, rendered into the document where a reader cannot tell it from
documentation. `assets[].notes` had zero uses and went with it.

Closes #194
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.

Give the catalog an apis field, and take notes away

1 participant