|
| |
|
|
| |
| 2.11 API函数的文档写法 |
API函数往往是被人经常用到的，所以对API的说明一定要简单，易懂，还要有足够的信息量。在写API函数时，基本上格式比较固定，可以含有以下内容。
√函数名
√函数调用形式
√函数功能概要
√输入参数
√返回值
√出错信息
大家往往不会写功能概要。功能概要只是告诉使用者该如何使用所描述的API。可以简明扼要，如有调用条件，注意事项，也可以写入。
根据以上的内容，可以将上面提到的函数写成如下的形式。
Cli_proc_clear_fltr - 清除Filter内容
【函数形式】
ERRCLI Cli_proc_clear_fltr(psw_uint32_t cmd_id, char *param)
【功能概要】
清除指定Filter的内容。首先对输入参数进行检查，检查正常时，在经过参数找出Filter的地址和长度，并将这些数据作为参数，调用PSW的有关API。
（如有注意事项，调用条件等，也可以写在功能概要中）
【输入参数】
psw_uint32_t cmd_id ：命令ID
char *param ：指定Filter的指针
【返回值】
CLI_OK： 正常
CLI_NG： 错误
【返回值出错理由】
①特権错误
②実行環境(ACT)错误
③调用API错误
下面是两个RTOS的API函数的例子。 |
|
|
| 从以上的例子中，可以看出在使用API时，需要注意的事项以及其内部处理的情况作了非常详细的说明。由于API被很多不特定的人使用，为了让使用者不借助与他人的情况下，就能看懂API该如何使用是非常重要的。 |
 |
|
|
|
