chore: prettify treeland-capture protocol

[asterwyx]

Put requests together and events together.

Log: 对齐treeland-capture协议格式
Influence: None

[deepin-ci-robot]

deepin pr auto review

这份代码是对 Wayland 协议 XML 文件 treeland-capture-unstable-v1.xml 的修改。主要涉及接口内部元素（请求、事件、枚举）的顺序调整。这种调整通常是为了遵循协议设计规范，使协议更符合逻辑和易于阅读。

以下是针对该 diff 的详细审查意见，分为语法逻辑、代码质量、代码性能和代码安全四个方面：

1. 语法逻辑

审查意见：逻辑结构更加规范，符合 Wayland 协议设计惯例。

• 接口元素排序：

  • 改进点：在 treeland_capture_frame_v1 和 treeland_capture_context_v1 接口中，修改将 destroy 请求移到了接口的最前面（或紧随枚举之后），将 copy 请求移到了 buffer 事件之前，并将 capture 和 create_session 请求移到了 source_ready 事件之前。
  • 解释：Wayland 协议规范通常建议按照特定顺序排列接口成员：
    1. enum 定义
    2. request（其中 destroy 通常排在第一位）
    3. event
    4. request 的回调（如果有）
  • 结论：原代码中，destroy 请求被放在了中间，且请求和事件的顺序交错（例如 buffer 事件在 copy 请求之前）。修改后的代码将这些请求归类并前置，使得协议的交互流程（客户端发起请求 -> 服务端响应事件）在阅读上更清晰，符合 Wayland 的标准风格。

• 枚举定义位置：

  • 改进点：在 treeland_capture_frame_v1 中，flags 枚举被移动到了 destroy 请求之后。
  • 解释：将枚举定义放在接口的早期位置有助于阅读者在查看具体请求或事件之前先了解相关的数据类型。这是良好的组织方式。

2. 代码质量

审查意见：提高了协议的可读性和可维护性。

• 可读性：通过将相关的请求（如 capture 和 create_session）集中放置，并遵循标准的请求-事件顺序，开发者阅读协议文件时能更快地理解 API 的使用流程。
• 空白符处理：Diff 中包含了一些空行的增删（例如接口末尾的空行），这有助于区分不同的逻辑块，使 XML 结构更清晰。
• 描述准确性：虽然主要是移动位置，但保留了原有的描述文本，未引入歧义。不过，建议在后续审查中确认描述文本是否完全准确（例如 capture 请求中的 "This event can be called..." 描述略显生硬，因为它是请求而非事件，建议改为 "This request can be called..."，但这不在本次 diff 的修改范围内）。

3. 代码性能

审查意见：无直接影响。

• 解释：Wayland 协议 XML 文件是接口描述文件，用于生成 C 语言或其他语言的绑定代码（头文件）。XML 文件中元素顺序的改变通常不会影响生成的二进制代码的执行效率或内存占用。生成的代码逻辑功能保持不变。

4. 代码安全

审查意见：无安全影响。

• 解释：本次修改仅涉及元素顺序的调整，未修改任何接口签名、枚举值、权限控制或安全相关的描述。因此，不会引入新的安全风险，也不会修复现有的安全问题。

总结与建议

这份 diff 是一次代码重构，主要目的是为了规范化协议接口的定义顺序。

• 优点：
  • 遵循了 Wayland 协议的最佳实践（请求在前，事件在后，destroy 靠前）。
  • 提升了协议文件的可读性和专业性。
• 建议：
  • 确认生成代码：虽然 XML 顺序改变通常不影响功能，但建议在应用此 diff 后，重新生成绑定代码并进行编译测试，确保构建系统没有因顺序变化而产生意外警告或错误。
  • 文档一致性：确保相关的文档或注释也反映了这种结构上的优化，尽管这通常不是必须的，因为 XML 本身即是文档。

总体而言，这是一次高质量的代码整理工作。

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: asterwyx, wineee, zccrs, zzxyb

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• debian/deepin/OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment