[RFC] 函数及函数指针声明中指针类型参数的文档编写标准

[moomiji]

实际为引用行为的指针 | 指向数组的指针

• [in] 属性：用于指示数据应从 调用方 传入 到 被调用方，被调用方 不可 修改数据。
• [out] 属性：用于指示数据应从 被调用方 传回 到 调用方 ，被调用方 可 修改数据。
• [in, out] 属性：用于指示数据既需要 被调用方 读取，又需要 被调用方 修改后反映回 调用方。

例外

• MaaStringView (const char*): 对于 C 库中使用 char 数组来表示字符串的情况，不需要标注 [in, out] 属性。

示例

1. 标注必须在 @param[<dir>] 中进行。相关文档
2. 指向数组的指针必须在参数中明确标出 array 关键字，即 /**< array */ ，避免开发者误解为引用。

    /**
     * @param[in] value The option value.
     */
    MAA_FRAMEWORK_API MaaBool
        MaaSetGlobalOption(MaaGlobalOption key, MaaOptionValue value /**< Maybe a byte array */, MaaOptionValueSize val_size);

    /**
     * @param[out] node_id_list
     * @param[in, out] node_id_list_size
     */
    MAA_FRAMEWORK_API MaaBool MaaQueryTaskDetail(
        MaaTaskId task_id,
        /* out */ MaaStringBufferHandle entry,
        /* out */ MaaNodeId* node_id_list /**< array */,
        /* in & out */ MaaSize* node_id_list_size);

错误示例

• 例1 https://github.com/MaaXYZ/MaaFramework/blob/d6177f2013c7c6087991c029ad3998001141a33b/include/MaaFramework/Instance/MaaCustomController.h#L48-L49

对 Binding（被调用方） 而言， 需要将图片数据写入 buffer 传回 Maa（调用方）。

但实际数据为 MaaImageBufferHandle，由 Maa（调用方）传入 Binding（被调用方）。

故 buffer 参数的文档应使用 [in] 属性而不是 [out] 属性，指示 Binding 不可修改 MaaImageBufferHandle。

当然，由于 MaaImageBufferHandle 实际上就是一个 Handle 作为数据在传来传去，并不属于 实际为引用行为的指针，不需要在文档中明确标注。

• 例2 https://github.com/MaaXYZ/MaaFramework/blob/d6177f2013c7c6087991c029ad3998001141a33b/include/MaaFramework/Instance/MaaResource.h#L100-L120

上面的 MaaStringBufferHandle 也不属于 实际为引用行为的指针，因此 @param[out] 属于多余标注。

[MistEO]

快点端上来吧.jpg