RFC-0054：参数属性

“A Chance to write self documenting APIs”（撰写自文档 API 的机会）

摘要

我们已经可以将属性应用于 FIDL 的各种元素，但不能应用于参数。这是一份提案，旨在扩展语法以接受参数属性。

与其他 RFC 的关系

此 RFC 已被以下 RFC 取代：

• RFC-0050：语法改进

设计初衷

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

此功能的主要用例是检查句柄泄漏、重复释放和释放后使用错误。

内核 ABI（即系统调用）也采用 FIDL 格式表示，并且句柄的所有权通常不明确。用户是否应在 task_kill 系统调用后调用 handle_close？文档中并未明确说明这一点。其他系统调用有非常明确的文档，但只能通过手动方式进行检查：

[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);
};

为参数启用属性后，我们可以将注释替换为属性。这些属性的易读性与注释相当，它们可以帮助生成器生成可使用静态和动态分析工具（例如 this）检查的代码。kazoo 工具可以为 C 和 C++ 绑定生成相应的注解，使 Clang 静态分析器能够捕获句柄滥用错误。

原型已经在 Fuchsia 中发现了一些 bug。

设计

该提案旨在向 FIDL 源语言添加参数属性。这些属性应以与其他属性类似的方式在 JSON IR 中公开。我们可能需要更新格式设置。这不会影响线格格式。语言绑定仅会受到引入可更改生成的代码的特定注解的影响，但不会直接受到此提案的影响。

我们的提案只会更改 FIDL 语法的一个生成式规则：

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

我们还需要诊断参数的三斜线文档或文档属性。

实施策略

此更改向后兼容，无需迁移。许多文档都需要随着该功能一起更新。此提案将更改解析器并向 IR 添加新信息。在引入新参数属性时，可以单独对生成器进行更改。

工效学设计

这有望使 FIDL API 更易于理解，并使绑定更适合进行静态和动态分析。额外的复杂性开销应较低。如需查看包含潜在参数属性的示例，请参阅下一部分。编辑器支持可能也需要进行一些小更新。

文档和示例

语法文档和语言参考需要进行一些更新。我们可能需要添加一些样式准则，说明在某些情况下如何为参数属性换行。这可能不是很重要，因为当前的样式指南中根本没有提及属性。

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

向后兼容性

此提案同时保持了 FIDL 源代码和线程 ABI 兼容性。后续引入的特定属性可能会导致线程 ABI 不兼容。这些属性应单独通过 RFC 流程。

性能

Future 属性可能会对性能产生良好影响。详细了解这些 API 可能会对目标语言的优化器有所帮助。

安全

这些特定属性可能会提高安全性，因为它们可以帮助目标语言中的静态和动态分析工具。

测试

我们将为 fidlc 编写测试，以确保正确解析，并针对编译失败提供合理的诊断信息。系统还会测试生成的 JSON IR。为了能够进行测试，我们需要引入至少一个适用于参数的属性。由于生成器一开始不会被触及，因此不需要进行额外测试。

缺点、替代方案和未知情况

实现成本相对较低。

RFC-0044 是一种可能的替代方案。接受该提案会在语言中引入一些不一致之处，因为一种描述参数的方法会让用户能够编写参数属性，而另一种方法则不会。此外，RFC-0044 会带来性能开销，因此某些协议（例如系统调用）应尽量少用或根本不使用它。

在先技术和参考文档

Protobuf 对消息具有选项，其行为与参数属性略有相似。FIDL 已经为成员和协议等一些语言元素提供了属性。