comment
Last modified by Lucas Charpentier on 2026/10/27 10:27
Audit
- Macro ID
- comment
- Source
- XS
- Type
- Wrapper
- Classification reason
- The macro outputs nothing. Its only data is the text the user types in its content, which it hides from view mode instead of decorating it, so it is closer to a wrapper than to a generator.
- Status
- Reviewed
- Criteria version
- 15.20
- XWiki version
- 18.8.0
- Audit date
- 2026-10-13
- Auditor
- Compared macros
- html velocity
Lucas CharpentierSources
Where to gather the information the criteria are checked against, see Gather the sources.
| Other sources specific to this macro |
|---|
|
| Criterion | Result | Notes |
|---|---|---|
| D1 wording | KO | "Comment" is confused with the page comments of XWiki, which this macro does not add, especially in the Quick Actions menu where users look for a feature by its name. The pretty name should at least be reconsidered, to say that the text is hidden from readers. |
| D2 summary | OK | |
| D3 category | KO | the macro is in the Development category, like html and velocity. A user writing a hidden note in the page does not look for it there; a note for other editors belongs to the annotations feature instead. The category should at least be reconsidered. |
| D4 quick-action | KO | Quick Actions and the Insert Macro dialog find the macro first for "comment" and for the French name "Commentaire". The synonyms "note", "remark", "hidden" and "annotation" give no result in either. |
| L1 consistency | OK | compared with html and velocity: like them, the content is mandatory, has no default, the Quick Action opens the Edit Macro dialog and the content is typed in its text area. |
| L2 doc-parameters | KO | minor: the documentation says "No parameters." and does not describe the content, nor that it is mandatory. |
| L3 doc-example | OK | |
| I1 pattern | KO | the reference wrapper, warning, is inserted by its Quick Action without a dialog; the comment Quick Action opens the Edit Macro dialog, see I3. It follows the generic behavior of macros without a dedicated Quick Action, like html and velocity. |
| I2 zero-config | OK | the dialog cannot be submitted with the default values, since the content is mandatory and empty: it stays open, with no message. OK, leniently: this is the generic behavior of the dialog for a missing mandatory value. {{comment/}} renders with no error. |
| I3 instant | KO | inserting from the Quick Actions menu with "/comment" and Enter opens the Edit Macro dialog with an empty Content text area; the macro is only inserted after typing a text and submitting. |
| I4 cursor | KO | after submitting the dialog, the macro widget is selected and the cursor is not in its content: the content cannot be typed in place, see E6. |
| I5 focus | N/A | |
| E1 wysiwyg | OK | the editor shows the generic "macro:comment" placeholder and view mode shows nothing. The placeholder is an editor element, but it does not show the comment text, see E6. |
| E2 errors | N/A | the macro has no parameter and accepts any text as content, so there is no invalid value to test. |
| E3 nesting | OK | |
| E4 inline-support | OK | |
| E5 empty | KO | minor: the empty macro keeps the visible "macro:comment" placeholder, which one click selects but never puts the cursor in: the content can only be typed in the Edit Macro dialog, see E6. Ideally the comment would stay compact and be edited in a dropdown or popup from the placeholder. |
| E6 inplace | KO | the content is never shown in the editor, which only displays "macro:comment": reading or changing a comment needs opening the Edit Macro dialog, where it is a plain text area. For example, {{comment}}Remember to update this table every release.{{/comment}} shows only "macro:comment" in the editor. |
Parameters
| Parameter | C1 clarity | C2 mandatory | C3 defaults | C4 input-assistance | C5 groups | C6 order | C7 alternatives | C8 advanced | C9 technical | C13 constraints | Notes |
|---|---|---|---|---|---|---|---|---|---|---|---|
| $content | KO | OK | N/A | OK | N/A | OK | N/A | N/A | N/A | N/A | C1: the description "Comments." does not say that the text is hidden from readers and only visible to editors. C4: a plain text area in the Edit Macro dialog, counted under E6. |
KOs and tickets
Every KO needs a ticket covering it, see Report the KOs. One ticket can cover several KOs. Known issues filed for this macro are suggested in italics: link them as existing tickets when they cover the KO.
| KO | Criterion | Existing tickets | New tickets |
|---|---|---|---|
| D1 | D1 wording | XWIKI-25493 | |
| D3 | D3 category | XWIKI-25493 | |
| D4 | D4 quick-action | XWIKI-25444 | |
| L2 | L2 doc-parameters | XINFRA-525 | |
| I1 | I1 pattern | XWIKI-25563 | |
| I3 | I3 instant | XWIKI-25563 | |
| I4 | I4 cursor | XWIKI-25569 | |
| E5 | E5 empty | XRENDERING-831 | |
| E6 | E6 inplace | XRENDERING-831 | |
| C1:$content | C1 clarity, $content | XWIKI-25493 |
Tickets
| Ticket | Origin | KOs covered | KOs partly covered |
|---|---|---|---|
| XWIKI-25444 | New | D4 | |
| XWIKI-25493 | New | C1:$content D1 D3 | |
| XINFRA-525 | New | L2 | |
| XWIKI-25563 | New | I1 I3 | |
| XRENDERING-831 | New | E6 E5 | |
| XWIKI-25569 | New | I4 |
Known issues of this macro
No known issue is specific to this macro.
68 more known issues affect every macro: see the Known issues.
