[RFC] protocol: Suggestion for wl_data_offer.finish request description improvement
Hi all, I hope this email finds you well. I’ve been reviewing the documentation for the wl_data_offer.finish request and would like to suggest a few minor improvements to enhance clarity and correctness. Current Description: `` Notifies the compositor that the drag destination successfully finished the drag-and-drop operation. Upon receiving this request, the compositor will emit wl_data_source.dnd_finished on the drag source client. It is a client error to perform other requests than wl_data_offer.destroy after this one. It is also an error to perform this request after a NULL mime type has been set in wl_data_offer.accept or no action was received through wl_data_offer.action. If wl_data_offer.finish request is received for a non drag and drop operation, the invalid_finish protocol error is raised. "It is also an error to perform this request after a NULL mime type has been set in wl_data_offer.accept or no action was received through wl_data_offer.action." `` Suggested Changes: Replace "no action" with "none action" in the sentence: Original: "or no action was received through wl_data_offer.action." Suggested: "or none action was received through wl_data_offer.action." (Note: This change assumes "none action" is the intended phrasing. If "no action" is technically correct, please disregard this suggestion.) Clarify the subject in the last sentence for better readability: Original: "If wl_data_offer.finish request is received for a non drag and drop operation..." Suggested: "If the compositor received wl_data_offer.finish request for a non drag and drop operation..." Rationale: The first change aligns with potential grammatical preferences (though "no action" may also be correct; please verify the intended phrasing). The second change makes it explicit that the compositor is the entity handling the request, improving clarity. These adjustments aim to make the documentation more precise while retaining its original meaning. Thank you for considering these suggestions. Please let me know if further clarification would be helpful. Best regards, 苏怀安
[RFC] protocol: Clarify mediator role of compositor in wl_data_offer description
Hi all, While reviewing the protocol documentation, I noticed that the description of wl_data_offer could more clearly reflect the actual mediation role of the compositor in data transfer. Current Description (problematic) `` A wl_data_offer represents a piece of data offered for transfer by another client (the source client). It is used by the copy-and-paste and drag-and-drop mechanisms. The offer describes the different mime types that the data can be converted to and provides the mechanism for transferring the data directly from the source client. `` This could be misinterpreted as implying direct client-to-client transfer, obscuring the compositor's critical role. Proposed Revision `` A wl_data_offer is created by the compositor to mediate data transfer between clients. The source client interacts via wl_data_source, while the destination client uses this interface. It enables: - MIME type negotiation through the compositor - Secure data transfer orchestration - Both clipboard and drag-and-drop operations `` Key Clarifications Compositor as mediator Explicitly states the compositor creates/manages wl_data_offer Matches actual implementation (Weston/wlroots) Role separation Distinguishes wl_data_source (source) and wl_data_offer (destination) Avoids "direct transfer" implication Protocol accuracy Aligns with the security model where all transfers are compositor-supervised Would appreciate feedback on whether this warrants a protocol patch. A minimal documentation update could prevent client implementation confusion. Best regards, 苏怀安
[RFC] protocol: Ambiguous description of wl_data_device.leave event
Hi all, In the protocol description of wl_data_device.leave event [1], the phrase "session ends" could be misinterpreted to include intra-client surface switches. However, the actual implementation only triggers this event when leaving the entire client. Suggested clarification: - Old: "when the drag-and-drop pointer leaves the surface and the session ends" - New: "when the drag-and-drop pointer leaves the client's surfaces entirely, terminating the cross-client session" [1] https://wayland.freedesktop.org/docs/html/apa.html#protocol-spec-wl_data_device
