关于结构化文本(ST)及Wago e!cockpit是否支持类Python/C++文档字符串功能的问询

一、ST本身的文档标注能力 #

IEC 61131-3标准里并没有像Python、C++那样原生定义文档字符串语法，但行业内的PLC开发环境基本都支持注释驱动的文档标注——说白了就是用特定格式的注释来模拟文档字符串的功能，这类注释会被IDE识别，在代码提示、文档生成时发挥作用。

二、Wago e!cockpit的具体支持 #

Wago e!cockpit完全吃这套玩法，常用的标注格式有两种：

• 多行注释文档：在变量、函数、FB块的上方用(* ... *)包裹多行注释，按约定好的标签编写内容
• 单行注释：针对单个变量、代码行做简短说明

举个函数块的例子：

(*
@描述: 计算两个整数的和
@输入: i_A - 第一个加数
@输入: i_B - 第二个加数
@输出: o_Sum - 两数之和
@版本: 1.0
*)
FUNCTION_BLOCK FB_Add
VAR_INPUT
    i_A : INT;
    i_B : INT;
END_VAR
VAR_OUTPUT
    o_Sum : INT;
END_VAR
o_Sum := i_A + i_B;
END_FUNCTION_BLOCK

当你把鼠标悬停在FB_Add上时，e!cockpit会直接弹出包含这些描述的提示框，和主流语言的文档字符串提示效果一致。

再比如单个变量的注释：

(* 设备运行状态：0=停止，1=运行，2=故障 *)
n_RunStatus : INT;

三、正式文档生成 #

如果需要导出项目的正式文档，e!cockpit可以把这些注释内容整合进去：右键工程 → 导出 → 选择「文档」选项，就能生成包含所有规范注释元素的PDF或HTML文档，省去手动整理的麻烦。

四、小提醒 #

• 注释标签没有强制的统一标准，但建议团队内部约定好（比如统一用@描述、@输入这类标签），方便协作和IDE识别
• 区分好文档注释和普通注释：文档注释是给工具和后续开发者看的，要简洁明确；普通注释可以写一些代码实现的细节思路

内容的提问来源于stack exchange，提问作者Benemenn