PlantUML中如何在箭头消息语句行尾添加内联注释？

核心原因 #

不同语句下注释生效表现不一致，本质是PlantUML解析器的逻辑区别：

• participant这类声明语句，解析器读取完关键字、别名等必要参数后，会自动忽略行尾剩余的块注释（/' ... '/）内容，所以行尾注释可以正常生效
• A -> B这类消息箭头语句，解析器默认将箭头符号后到行尾的所有内容都识别为要渲染的消息文本，不管是单引号注释还是块注释，只要没有显式标记消息文本结束位置，都会被当成普通内容渲染到图中，不会被识别为注释。

目前PlantUML原生语法没有提供无消息文本的箭头语句行尾直接添加内联注释的官方支持，可以通过以下几种方案实现需求：

可行实现方案 #

1. 注释单独邻行放置（全版本兼容推荐） #

这是兼容性最高、不会出现解析异常的通用写法，适配所有PlantUML版本和所有图类型，只需要把注释放在对应箭头语句的紧邻上一行即可，代码阅读时的对应关系非常清晰：

@startuml
    participant Alice as A
    participant Bob as B

    ' A向B发起初始请求
    A -> B
    ...
@enduml

2. 同行行内注释hack写法 #

如果一定要把注释和箭头写在同一行，可以给箭头显式添加空消息标记（冒号+空格），再在后面跟块注释，注释内容会在文本解析阶段被过滤，不会渲染到最终生成的图中：

@startuml
    participant Alice as A
    participant Bob as B

    A -> B:  /' 这里是同行行尾注释，不会显示在图上 '/
    ...
@enduml

注意这个写法必须保留冒号和后面的空格，省略冒号的话解析器还是会把块注释识别为消息文本。

3. 新版本适配写法 #

2023年之后发布的PlantUML新版本，对时序图消息解析逻辑做了调整，在有显式消息文本的箭头语句中，消息文本后用两个及以上空格分隔，再跟单引号开头的单行注释，也可以被正常识别，不会渲染到图中：

@startuml
    participant Alice as A
    participant Bob as B

    A -> B: 接口请求  ' 这是行尾注释，仅新版本支持
    ...
@enduml

这个写法兼容性较差，在旧版本PlantUML环境中会把注释内容当成消息文本的一部分渲染，仅适合确定渲染端版本的场景使用。

避坑提示 #

• 不要在不带显式消息冒号的箭头语句行尾直接加任何格式的注释，一定会被解析为消息内容
• 如果文档需要在多个不同内置PlantUML渲染器的平台展示，优先选择注释单独邻行的写法，避免出现渲染错乱。

内容的提问来源于stack exchange，提问作者41 72 6c