[ako]

Fixes mendixlabs#1510 (#1392). The maintainer chose option (a): let MDL write the documentation that QUAL002 asks for. Two commits.

Syntax

No new keywords. The existing /** … */ doc comment above a create is now stored, as it already is for JSON structures:

/** Reads an order line from the shop API. */
create [or modify] import mapping M.IMM … | export mapping … | published rest service … | data transformer …

• Rewrites: on create or modify, leaving out the comment keeps the stored text, and an empty /** */ clears it (the same rule as MDL-BUTTON02: also flag own-container names in data sources and widget expressions #1018).
• Describe: prints the documentation back. Text containing */ is printed as -- lines, so running the output keeps the stored text.
• Java action parameters: descriptions (/** desc */ Param: Type) were already added on main by create java action cannot set parameter descriptions or the return value name; the -- … form that describe prints is silently dropped mendixlabs/mxcli#1588. They are verified end to end here and covered by the bug-test script.

Root causes (commit 1)

1. The comment was dropped. The four create AST structs had no Documentation field, so the comment was classed as detached (MDL089) and never read.
2. Existing documentation was erased on rewrite. None of the four executors set the documentation, so create or modify wrote an empty value over it. The data transformer writer wrote a hard-coded "". A PedApp test proves that describe → exec of a Studio Pro-documented mapping deleted its documentation.
3. QUAL002 could never be satisfied for published REST. The catalog wrote "" for published_rest_services.Documentation, so QUAL002 flagged every service, even ones documented in Studio Pro.

Fix:

• AST fields and doc-comment reading in the visitors.
• The executors set the documentation and carry the stored value when no comment is written.
• model.PublishedRestService and model.DataTransformer gain Documentation, read and written by the backend.
• Documentation is no longer in the published REST service's unauthored set. PublicDocumentation (the OpenAPI text) is still carried as stored.
• A shared describe helper, and the catalog now stores the value.

BSON field verified: a top-level Documentation string on ImportMappings$ImportMapping, ExportMappings$ExportMapping, Rest$PublishedRestService and DataTransformers$DataTransformer. The evidence:

• the generated types;
• the raw Studio Pro-stored PedApp mappings;
• mx dump-mpr showing each MDL-written comment as that unit's documentation, on 11.6.6 and 11.15.

Commit 2: MDL089 message

For a doc comment above a create that can't store one, MDL089 used to say "move it above the next create". That would attach the comment to a different element. It now says MDL can't store documentation for that element and suggests a -- comment. Drop, grant, revoke, set and alter keep the old suggestion.

Measured

Fixture	Script	mx check	describe shows docs	QUAL002 on the documented elements
11.6.6	bug test, minus the data transformer (11.9+)	0 errors	yes	none
11.15.0	full bug test	0 errors	yes	none

Lint control: undocumented copies of the same elements still give 4 QUAL002 findings.

Tests

• TestIntegrationDocumentsReadDocComment_Issue1510 (visitor).
• TestIntegrationDocumentation_Issue1510 (PedApp copy): stored key, describe → exec round trip, carry, and /** */ clearing.
• TestIntegrationDocumentation_StudioProMappingKeepsIt_Issue1510.
• TestPublishedRestServiceDocumentationReachesCatalog_Issue1510, with an undocumented service as control.
• TestDocumentation_SurvivesRewrite gets four new cases (-tags integration, against an mx 11.15 project).
• TestValidateProgram_DetachedDocCommentOnCreate_Issue1510.

Revert check:

• With the fix reverted, every new test fails with the reported symptom.
• With only the carry stubbed out, the rewrite and Studio Pro cases fail.

Also in this PR: syntax help (import mapping, export mapping, data transformer, published REST), docs-site reference pages, the json-structures-and-mappings skill, two finding files, and mdl-examples/bug-tests/1510-documentation-for-mappings-rest-javaparams.mdl. make build, make test, make lint, check-findings, check-skill-index and check-skill-mdl pass.

For review

• Behaviour change: create or modify of a published REST service with a doc comment now overwrites the stored documentation. Before, the stored text was always kept.
• Not fully verified:
  • The -- fallback for text containing */ has no test.
  • The repo has no Studio Pro-stored published REST service or data transformer unit, so for those two the field is verified through the generated types and Mendix's own reader.

---

Generated by Claude Code