Document the types passed to each wl_listener

[DemiMarie]

wl_listener.notify only gets a void * so the actual parameter type needs to be documented.

---

wlroots has migrated to gitlab.freedesktop.org. This issue has been moved to:

https://gitlab.freedesktop.org/wlroots/wlroots/-/issues/3239

[ifreund]

I've documented these in the type system of zig-wlroots but haven't found time to port this information back to the upstream wlroots headers in the form of comments. For example:
https://github.com/swaywm/zig-wlroots/blob/d2df3f71578eb767bced89ae1044a046b7fa22a0/src/types/output.zig#L156-L168

    events: extern struct {
        frame: wl.Signal(*Output),
        damage: wl.Signal(*event.Damage),
        needs_frame: wl.Signal(*Output),
        precommit: wl.Signal(*event.Precommit),
        commit: wl.Signal(*event.Commit),
        present: wl.Signal(*event.Present),
        bind: wl.Signal(*event.Bind),
        enable: wl.Signal(*Output),
        mode: wl.Signal(*Output),
        description: wl.Signal(*Output),
        destroy: wl.Signal(*Output),
    },

These are already documented by comments in some places in wlroots, but not all.

[emersion]

Note, in some places the doc comment is missing, but that just means "no data"/NULL.

[ifreund]

Note, in some places the doc comment is missing, but that just means "no data"/NULL.

Currently wlroots usually passes a pointer to the struct itself is there is no doc comment. For example in wlr_output the events field is:

wlroots/include/wlr/types/wlr_output.h

Lines 152 to 173 in 13cdb84

	struct {
	// Request to render a frame
	struct wl_signal frame;
	// Emitted when software cursors or backend-specific logic damage the
	// output
	struct wl_signal damage; // wlr_output_event_damage
	// Emitted when a new frame needs to be committed (because of
	// backend-specific logic)
	struct wl_signal needs_frame;
	// Emitted right before commit
	struct wl_signal precommit; // wlr_output_event_precommit
	// Emitted right after commit
	struct wl_signal commit; // wlr_output_event_commit
	// Emitted right after the buffer has been presented to the user
	struct wl_signal present; // wlr_output_event_present
	// Emitted after a client bound the wl_output global
	struct wl_signal bind; // wlr_output_event_bind
	struct wl_signal enable;
	struct wl_signal mode;
	struct wl_signal description;
	struct wl_signal destroy;
	} events;

However wlroots passes a struct wlr_output * as the data pointer for the events without doc comments.

Is this intentional?

[emersion]

It's mostly cargo-culting. I'd like to stop doing this and replace all of these with NULL, because this would allow us to extend the API without breaking it (ref #1008 (comment)).

[DemiMarie]

It's mostly cargo-culting. I'd like to stop doing this and replace all of these with NULL, because this would allow us to extend the API without breaking it (ref #1008 (comment)).

Does that include constructor events? Presumably a new_surface event needs to pass the wlr_surface somehow.

[emersion]

This doesn't include listeners with an already-useful data pointer, such as new_surface.