注释用来解释代码,不影响功能。主要分为四种:注释块、文档注释块、单行注释、单行文档注释。
以 /* 开始,*/ 结束,可跨行。
/* #include <amxmodx>表示按照以下顺序尝试寻找amxmodx.inc文件:
* "当前文件所在目录"->"-i参数所指目录"->"编译器目录下的include文件夹"
* 若找到就从这一行开始引用amxmodx.inc文件的所有内容,包括它内部引用的其它文件内容。
*/
#include <amxmodx>
/* public plugin_init() { }表示声明、定义一个名为plugin_init的公共函数。
* 只要引用了amxmodx.inc文件,游戏启动,载入地图并缓存所有资源文件之后,
* 就会执行plugin_init函数的定义(花括号内容)。
*/
public plugin_init() { }
文档注释块是注释块的一种特殊形式,以 /** 开头,以 */ 结尾。
里面通常包含一些固定标签,比如:@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或在线翻译网站进行翻译: