docs: clarify dde-shell surface lifetime on early wl_surface destroy

[wineee]

1. Document that destroying wl_surface first does not destroy the treeland_dde_shell_surface_v2 object server-side.
2. Specify that the object becomes inert, with further requests silently ignored and no protocol error raised.
3. State that the object is destroyed only by the client's destroy() request or when the client disconnects.

Log: Protocol lifetime semantics clarified for out-of-order destroy.

Influence:

1. Run ./check-protocol-xml.sh dde/treeland-dde-shell-unstable-v2.xml and confirm wayland-scanner exits clean.
2. Review that the description no longer claims server-side auto-destroy on wl_surface destruction.
3. Verify the doc matches compositor behavior when a client destroys wl_surface before the shell surface.

docs: 明确 dde-shell surface 在 wl_surface 提前销毁时的生命周期

1. 说明先销毁 wl_surface 不会导致服务端销毁 treeland_dde_shell_surface_v2 对象。
2. 明确对象转为 inert，后续请求被静默忽略且不触发协议错误。
3. 说明对象仅由客户端 destroy() 请求或客户端断开连接时销毁。

Log: 明确乱序销毁场景下的协议生命周期语义。

Influence:

1. 运行 ./check-protocol-xml.sh dde/treeland-dde-shell-unstable-v2.xml 并确认 wayland-scanner 退出码为 0。
2. 检查描述中不再声称服务端会在 wl_surface 销毁时自动销毁对象。
3. 核对文档与合成器在客户端先销毁 wl_surface 时的实际行为一致。

Summary by Sourcery

Clarify dde-shell surface lifetime behavior when clients destroy the associated wl_surface before the shell surface.

Enhancements:

• Clarify dde-shell surface lifetime semantics when the associated wl_surface is destroyed first, including inert-object behavior and the conditions that ultimately destroy it.

Documentation:

• Update the dde-shell protocol documentation to match compositor behavior for out-of-order surface destruction.

[deepin-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: wineee

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

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Updates the DDE shell protocol documentation to accurately describe out-of-order destruction: destroying wl_surface first leaves the shell-surface object inert, and it is reclaimed only through destroy() or client disconnection.

State diagram for DDE shell surface lifetime

stateDiagram-v2
    [*] --> Active
    Active --> Inert: wl_surface destroyed
    Active --> Destroyed: destroy()
    Inert --> Destroyed: destroy()
    Active --> Destroyed: client disconnects
    Inert --> Destroyed: client disconnects
    Inert --> Inert: further requests silently ignored

Loading

File-Level Changes

Change	Details	Files
Clarify the server-side lifetime and post-surface-destruction behavior of the shell-surface object.	Remove the claim that destroying the related wl_surface automatically destroys the shell-surface object. Document that the object becomes inert after early wl_surface destruction, with subsequent requests ignored without protocol errors. Specify that cleanup occurs only on the client's destroy() request or client disconnect.	dde/treeland-dde-shell-unstable-v2.xml

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="dde/treeland-dde-shell-unstable-v2.xml" line_range="89-90" />
<code_context>

+            If the client destroys the wl_surface without first destroying
+            the shell surface object, the compositor does not destroy the
+            shell surface object. The object becomes inert: any further
+            requests sent to it are silently ignored and no protocol error
+            is raised. The compositor destroys the object only when the
+            client sends destroy() or when the client disconnects, at
+            which point all of the client's resources are cleaned up.
+
             Positioning requests are mutually exclusive: set_position_hint
</code_context>
<issue_to_address>
**nitpick:** The description says that any further requests on the inert object are silently ignored, but `destroy()` is itself a further request and the following sentence says that sending it destroys the object. The lifetime rule is therefore internally contradictory for the only request that must remain functional after the wl_surface is destroyed.

**Triggers:** When the client destroys wl_surface first and then sends treeland_dde_shell_surface_v2.destroy().

**Suggested fix:** Say that all further requests except `destroy()` are silently ignored, or explicitly state that `destroy()` remains effective on the inert object.

```suggestion
            shell surface object. The object becomes inert: all further requests except
            destroy() are silently ignored and no protocol error
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[sourcery-ai]

nitpick: The description says that any further requests on the inert object are silently ignored, but destroy() is itself a further request and the following sentence says that sending it destroys the object. The lifetime rule is therefore internally contradictory for the only request that must remain functional after the wl_surface is destroyed.

Triggers: When the client destroys wl_surface first and then sends treeland_dde_shell_surface_v2.destroy().

Suggested fix: Say that all further requests except destroy() are silently ignored, or explicitly state that destroy() remains effective on the inert object.

Suggested change

	shell surface object. The object becomes inert: any further
	requests sent to it are silently ignored and no protocol error
	shell surface object. The object becomes inert: all further requests except
	destroy() are silently ignored and no protocol error