CREATE OR REPLACE / CREATE OR MODIFY deletes an object's doc comment (Documentation), silently

[ako]

Summary

A CREATE OR REPLACE / CREATE OR MODIFY statement that does not restate an
object's /** … */ doc comment deletes the object's Documentation from the
model. The run reports success, and nothing else reports anything.

ALTER ENTITY … ADD ATTRIBUTE does not have this problem, which both
localises the defect to the rewrite paths and gives users a workaround.

This is the guard-don't-drop class (ADR-0005) applied to a property MDL can
author but a rewrite does not carry.

Environment

• mxcli built from main at 7c2c9b1e (v0.20.0-148)
• Mendix model version 11.13.0, MPR v2 project
• Default (modelsdk) engine

Reproduction

-- 1-create.mdl
/** MF-DOC-MARKER: why this flow exists. */
create microflow MyFirstModule.MF_DocProbe ()
begin
end;

/** ENT-DOC-MARKER: why this entity exists. */
create entity MyFirstModule.EntDocProbe ( Label: String );

-- 2-alter.mdl
alter entity MyFirstModule.EntDocProbe add attribute Extra: Integer;

-- 3-modify.mdl
create or modify entity MyFirstModule.EntDocProbe ( Label: String, Extra: Integer );

-- 4-replace.mdl
create or replace microflow MyFirstModule.MF_DocProbe ()
begin
end;

Run each in order against the same project, checking the stored bytes after
each step rather than a read-back:

probe() { grep -qral "$1" "$PROJECT/mprcontents/" && echo PRESENT || echo ABSENT; }

Measured

                                   microflow doc   entity doc
1. after create                      PRESENT        PRESENT
2. after ALTER ENTITY add attribute  PRESENT        PRESENT
3. after CREATE OR MODIFY entity     PRESENT        ABSENT
4. after CREATE OR REPLACE microflow ABSENT         ABSENT

The untouched object is the control at every step, and it holds: each rewrite
destroys only its own object's documentation. Step 2 is the second control —
the same entity, a mutating statement, documentation preserved — which is what
rules out "documentation is lost on any write".

describe microflow also stops emitting the comment after step 4, consistent
with the bytes.

Expected

A rewrite that says nothing about documentation should carry the stored
documentation forward, the way it already carries the folder, the allowed module
roles and the element identity. Restating the doc comment should be optional, not
load-bearing.

Why this is worse than it looks

Documentation is where Mendix developers put the why — and a doc comment is
the spelling mxcli itself recommends, since create … comment 'text' was removed
in favour of it. So the property most likely to hold irreplaceable prose is the
one an ordinary edit discards.

Every signal reports success: mxcli check passes, exec prints
Replaced microflow / Modified entity, and the model stays valid — a document
with no documentation is legal, so no CE code exists for this. The loss is only
visible by diffing the stored unit or by noticing the text is gone in Studio Pro.

I did not run mx check on the result; I would not expect it to help, because
Documentation is an optional free-text property with nothing to validate. If
that assumption is wrong it is worth confirming.

Notes for a fix

• The preservation mechanism already exists for neighbouring properties on the
  same statements — folder, allowed module roles, StableId, element identity
  are all read off the stored document and carried. Documentation looks like it
  was simply not added to that set.
• Both engines should be checked. This was measured on the default (modelsdk)
  engine only.
• Worth checking the whole doc-comment surface at once rather than the two
  doctypes here: findDocCommentText is wired at 28 sites in mdl/visitor/
  (entity, microflow, page, association, enumeration, workflow, scheduled event,
  queue, regular expression, JSON structure, image collection, OData, REST,
  business events, agent-editor documents), and each has a rewrite path.
• A regression test wants the second control from step 2, or it cannot
  distinguish "rewrites drop documentation" from "writes drop documentation".

Context

Found while verifying assumptions for the project-brain proposal
(#1017), whose preferred storage tier is exactly "attach the
knowledge to the object's Documentation". That tier is unusable until this is
fixed, but the defect is independent of that feature.