docs(annotation): explain that Mendix has no annotation height (#1014)

[ako]

Refs mendixlabs#1014, which asks for a writable Height on domain-model annotations.

The feature cannot be built — Mendix has no annotation height

DomainModels$Annotation has exactly four properties: Caption, ExportLevel, Location, Width. The note auto-sizes to its caption, so there is nowhere to write a height into. Accepting Height: n would mean inventing a key the platform does not have, and it would be silently discarded.

The reporter's own aside — "Height values are determined by Studio Pro" — turns out to be the whole answer.

Why four sources, not one

generated/metamodel says the same, but on its own it could not settle this: it is an 11.6.0 snapshot and the report was against 11.12.2, so a property added since would be invisible to it.

source	result
generated/metamodel (11.6.0 snapshot)	caption, exportLevel, location, width
mx dump-mpr on 11.13.0, two projects	the same four keys
mx convert -p on 11.13.0	the same four — decisive
Mendix Model SDK docs (latest)	caption, exportLevel, location, width

mx convert is the one that settles it: it rewrites the model through Mendix's own object model, so a property that merely had a default and was not stored would be materialised. Nothing appeared. An absent key in stored BSON proves nothing by itself — it may just be unwritten — which is why the dump alone was not enough.

What this PR does instead

The reporter's actual goal (a note that does not overlap the entities below it) was reachable already, so the deliverable is an error that says which problem this is and names the levers that exist.

- line 5:2 mismatched input 'Height' expecting {POSITION, CAPTION, WIDTH}

  Mendix does not store an annotation height. DomainModels$Annotation has
  exactly four properties — Caption, ExportLevel, Location and Width — so the
  note auto-sizes to its caption and there is nothing to write a height into.
  Height follows from the wrapping, so WIDTH is the lever:
    Width: 300   -- narrower wraps to more lines, so the note is TALLER
    Width: 600   -- wider wraps to fewer lines, so the note is SHORTER
  To stop a note overlapping what sits below it, move those down:
    ALTER ENTITY Mod.Entity SET POSITION (x, y);

Both of those already work: ALTER ENTITY … SET POSITION makes entity layout fully scriptable (so nothing needs nudging by hand), and Width changes the wrapping and therefore the height.

A second branch covers any other unsupported property with the four-property statement, without the height-specific advice.

Both branches key on the expecting {POSITION, CAPTION, WIDTH} token set, not on the word "Height". That set is unique to annotationProperty and survives simplifyExpecting untouched (three tokens, no statement-start keywords). A page widget's Height is valid MDL, and a name-keyed hint would misfire on it — TestWidgetHeightIsNotAnnotationHinted is the control.

Docs: the syntax topic's "THERE IS NO COLOUR" paragraph becomes "THERE IS NO HEIGHT, AND NO COLOUR", and ast_annotation.go records the four-way measurement where the type is defined, so nobody re-derives it.

Verification

• Control: disabling both branches fails both hint tests; the widget control passes either way.
• Full suite green, gofmt clean, make check-findings 884 records, 206 skill MDL blocks pass.

One limit worth stating: this establishes what the model stores, not what Studio Pro's canvas draws. That the renderer derives height from caption + width follows necessarily from nothing being stored, but there is no Studio Pro here to watch it reflow.

Note on the issue

Suggest closing mendixlabs#1014 as not implementable rather than deferring it — the constraint is in the platform, so it will not change with an mxcli release. A reply is drafted and ready to post if wanted.

---

Generated by Claude Code