📘 AMXX源码的注释

注释用来解释代码,不影响功能。主要分为四种:注释块、文档注释块、单行注释、单行文档注释。

/* 注释块(多行注释) */

/* 开始,*/ 结束,可跨行。

/* #include <amxmodx>表示按照以下顺序尝试寻找amxmodx.inc文件: * "当前文件所在目录"->"-i参数所指目录"->"编译器目录下的include文件夹" * 若找到就从这一行开始引用amxmodx.inc文件的所有内容,包括它内部引用的其它文件内容。 */ #include <amxmodx> /* public plugin_init() { }表示声明、定义一个名为plugin_init的公共函数。 * 只要引用了amxmodx.inc文件,游戏启动,载入地图并缓存所有资源文件之后, * 就会执行plugin_init函数的定义(花括号内容)。 */ public plugin_init() { }

2. /** 文档注释块 */

文档注释块是注释块的一种特殊形式,以 /** 开头,以 */ 结尾。

里面通常包含一些固定标签,比如:@param@return@note 等,用于详细描述函数、常量、变量的用途。

这种注释主要出现在.inc文件中,供代码编辑器自动显示函数注释用。

文档注释块的正常格式示例:

/** * 这里对函数或其他标识符进行介绍。 * * @deprecated 这里解释其为什么已经被弃用。若未弃用则则省略。 * * @note 这里写使用该标识符的注意事项。无则省略。 * * @note 可继续写更多不同类的注意事项。 * * @param 参数1名称 函数的参数1应该输入什么,什么情况下会输出什么,无或非函数则省略 * @param 参数2名称 可继续写更多参数介绍。 * * @return 这里解释函数所有情况下会提供什么返回值。 * @noreturn 表示函数没有返回值,@noreturn与@return二选一,非函数则省略 * @error 介绍函数所有可能会出现的报错和原因,无或非函数则省略 */

请记住接下来的内容,因为你无法在其他地方找到如此正确详细的注释。教程通常会默认你已经学习过,跳过这些内容。

从 amxmodx.inc 中摘取并翻译、修正的文档注释块示例:

/** * 预声明插件初始化函数。有了此声明,缓存资源文件之后会调用所有插件定义的同名公共函数。 * * @note 需要在源码中用public声明符定义名为plugin_init的公共函数。像这样: * public plugin_init() * { * } * * @note 这个函数内是大部分插件进行初始化的好地方,例如设定插件信息, * 添加控制台变量或命令,添加事件挂钩,生成初始数据等等。 * * @noreturn */ forward plugin_init(); /** * 设置当前插件的信息。 * * @note 设置后,可在控制台发送以下4种命令查看效果: * amxx plugins - 显示所有已初始化插件简介(索引号、名称、版本、作者、文件地址等等) * amxx plugins 作者名称 - 查询该作者的所有已初始化插件简介 * amxx plugins 关键词 - 查询文件地址包含关键词的所有已初始化插件简介 * amxx plugin 插件索引号 - 查询特定插件的完整信息 * * @param plugin_name 插件名称 * @param version 插件版本 * @param author 插件作者 * @param url 插件的URL地址 * @param description 插件介绍 * * @return 返回当前插件的索引号 */ native register_plugin(const plugin_name[], const version[], const author[], const url[] = "", const description[] = ""); /** * 让服务器发送一段文本到控制台(所有人能看见)。 * * @note 使用方法示例: * new var1 = 10, var2 = 9; * server_print("[AMXX]我今天几岁了? %d 岁或 %d 岁了", var1, var2); * * @param message 被发送的文本。 * 格式化字符串支持包含 %b %c %d %i %u %f %X %x %a %s %L %l %N %n %% % 等格式占位符。 * 格式占位符表示将后续参数转换为某一样式的字符串,填充到自身位置。 * %b 需要1个单值参数,二进制样式。 * %c 需要1个单值参数,字符样式。 * %d 和 %i 完全相同,需要1个单值参数,十进制样式。 * %u 需要1个单值参数,无符号十进制样式。 * %f 需要1个单值参数,浮点数样式。 * %X 需要1个单值参数,大写十六进制样式。 * %x 需要1个单值参数,小写十六进制样式。 * %a 需要1个单值参数(字符串指针),字符串样式。 * %s 需要1个数组参数(字符串)。不转换。 * %L 需要1个单值参数(LANG_SERVER/LANGE_PLAYER/玩家实体索引)和1个数组参数(预设的可翻译字符串)。 * LANG_SERVER表示"使用服务端设定的语言"。 * LANGE_PLAYER表示"显示给谁就使用谁设定的语言"。 * 玩家实体索引表示"使用索引所指玩家设定的语言"。 * 预设的可翻译字符串来自register_dictionary函数。 * 将字符串转换为翻译后的内容。 * %l 需要1个数组参数(预设的可翻译字符串),显示给谁就使用谁设定的语言,将字符串转换为翻译后的内容。 * %N 需要1个单值参数(玩家实体索引),"玩家名称<队伍名称>"样式。 * %n 需要1个单值参数(玩家实体索引),转换为玩家名称。 * %% 不需要参数,而是将自身转换为 % 字符。 * % 不需要参数,而是会被删除。 * @param ... 这是可变参数,要求按照顺序填写格式占位符所需的参数 * * @return 实际发送的字符串元素数量 * @error 可变参数的数量不足预期。 * 可变参数为 %a 提供了无效的玩家实体索引。 * 可变参数为 %n 或 %N 提供了无效的玩家实体索引。 */ native server_print(const message[], ...); /** * 让特定玩家发送文本。 * * @note 使用方法示例: * new var1 = 10, var2 = 9; * client_print(playerEntityIndex, print_chat, "[AMXX]我今天几岁了? %d 岁或 %d 岁了", var1, var2); * * @param index 0=发送给所有玩家,玩家实体索引=发送给指定玩家 * @param type 消息类型,需填写amxconst.inc文件提供的名称以print_开头的枚举常量。 * print_notify=在开发者模式控制台发送。 * print_console=在控制台发送。 * print_chat=在聊天框发送。 * print_center=在窗口中心到顶部路径的3成位置居中发送。 * print_radio=在聊天框发送,若发送的是游戏预设文本,翻译为游戏设定语言。 * @param message 被发送的文本,支持格式占位符 * @param ... 这是可变参数,允许输入输出任何类型的参数。但这里要求按照顺序填写格式占位符所需的参数 * * @return 客户端接收的字符串元素数量(若发送给所有玩家,返回最后一个玩家接收的元素数量) * @error index非0且不是有效的玩家实体索引。 * 可变参数的数量不足预期。 * 可变参数为 %n 或 %N 提供了无效的玩家实体索引。 */ native client_print(index, type, const message[], any:...);

// 单行注释

单行注释以 // 开头,在 行尾 结束。

不可以在末尾出现\符号,因为这是续行符,而单行注释不允许被续行。

#include <amxmodx> const gConstant = 10; // 全局常量 public plugin_init() { const localConst = 20; // 局部常量 }

/// 单行文档注释

单行文档注释是单行注释的一种特殊形式,以 // 开头,在 行尾 结束。

通常用于简单描述全局常量、备用只读变量。同样不允许被续行。

/// 服务器能为玩家预留的实体槽最大数额 const MAX_PLAYERS = 32; /// 插件初始化入口 public plugin_init() { }

🌐 翻译工具推荐

遇到英文注释可使用ai或在线翻译网站进行翻译:

⚠️ 注意: 注释可能包含错误或不完整,尤其低版本 AMXX。最终要以实际行为或源码为准。

📖 下一篇

📄 05. 编译器指令 →