RFC-0054：参数属性

“编写自编文档 API 的机会”

摘要

我们已经可以将属性应用于 FIDL 的各种元素，但不能应用于参数。此建议旨在扩展语法，以接受参数属性。

与其他 RFC 的关系

此 RFC 已被：

• RFC-0050：语法改版

设计初衷

为更多语言元素添加属性可提高语言的一致性 也有助于未来推出更多功能。有关该 API 的任何信息 无法在类型系统中编码的 可以改为在属性中编码。 任何无法在类型系统中编码的事实都可以通过 结构，从而简化各种后端中的后期验证。这些 属性对执行 lint 请求很有用，而生成器也可以利用 以生成更好的代码，或将此信息传播到 目标语言。这有助于对目标进行静态和/或动态分析 语言。此外，属性是构建原型的好方法， 字体系统的扩展或优化。

此功能的驱动用例是检查句柄泄漏、双重释放 并在释放错误后使用。

内核 ABI（即系统调用）也以 FIDL 格式表示，通常 标识名的所有权不明确。用户是否应在 是否关闭 task_kill 系统调用？文档中未明确指出这一点。其他 系统调用提供了非常清晰的文档，但只能通过手动检查：

[Transport = "Syscall"]
protocol handle {
    /// Close a handle.
    /// Rights: None.
    handle_close(handle handle) -> (status status);

    /// Close a number of handles.
    /// Rights: None.
    handle_close_many(vector<handle> handles) -> (status status);

    /// Duplicate a handle.
    /// Rights: handle must have ZX_RIGHT_DUPLICATE.
    handle_duplicate(handle handle, rights rights) -> (status status, handle out);

    /// Replace a handle.
    /// Rights: None.
    handle_replace(handle handle, rights rights) -> (status status, handle out);
};

我们对参数启用属性后，就可以将注释替换为 属性。这些属性像注释一样可读， 生成器来生成可使用静态和动态 分析工具，例如此处。卡祖笛工具可以 为 C 和 C++ 绑定生成相应的注解，从而使 Clang 支持静态分析器 捕获句柄滥用错误。

原型已经在紫红色中发现了不少 bug。

设计

此方案是向 FIDL 源语言添加参数属性。这些 属性应在 JSON IR 中公开，方式与其他 属性。我们可能需要更新格式化程序。它不影响电线 格式。只有引入特定的 注解，可以更改生成的代码，但不受此变更的影响 提案

我们的方案仅更改 FIDL 的一条生产规则 语法：

- parameter = type-constructor , IDENTIFIER ;
+ parameter = ( attribute-list ) , type-constructor , IDENTIFIER ;

我们还需要诊断 参数。

实施策略

此更改可向后兼容，无需迁移。这里有很多 与功能一起更新的文档。此提案 会更改解析器并向 IR 添加新信息。可能会造成 可以单独创建生成器，此时新的参数属性 推出

工效学设计

可能会使 FIDL API 更易于理解，并加强绑定 适合静态和动态分析。额外复杂性的代价应该 较低。如需了解可能的参数属性示例，请参阅下一部分。 编辑器支持可能也需要进行小幅更新。

文档和示例

需要对语法文档和语言参考稍作更新。周三 可能需要添加一些样式准则，以便在特定情况下 参数的值。这可能不是很重要，因为属性 当前风格指南中提到的那些。

如需查看示例，请参阅动机部分。

向后兼容性

此方案保持 FIDL 源和线路 ABI 兼容性。通过 稍后引入的特定属性可能会导致传输 ABI 不兼容。要通过 RFC 流程，必须提供这些属性 。

性能

未来的属性可能会对性能产生良好影响。更多信息 API 可能对优化目标语言的优化有所帮助。

安全

具体属性可以提高安全性，因为它们可以帮助静态和 动态分析工具。

测试

测试将针对 fidlc 进行编写，以确保正确解析和合理的诊断 编译失败。系统还将测试生成的 JSON IR。为此， 我们需要引入至少一个 参数。由于生成器一开始不会被触发，因此 需要进行额外的测试

缺点、替代方案和未知问题

实现成本相对较低。

RFC-0044 是一个可能的替代方案。接受该提案 引入一些不一致之处，以此描述语言中的 参数可让用户编写参数属性，而 错误。此外，RFC-0044 会产生性能成本，因此某些协议（如系统调用） 应谨慎使用或完全不要使用

先验技术和参考资料

Protobuf 包含 options 消息，其行为与参数属性有一些类似。FIDL 某些语言元素（如成员和协议）已具有属性。