Revert "subcompositor: emit new_subsurface immediately"

new_subsurface emitted immediately isn't actually that useful. Revert the change
and document that this event is special.

This reverts commit 504b9491f0.

include/wlr/types/wlr_compositor.h

@@ -190,7 +190,12 @@ struct wlr_surface {
 		 */
 		struct wl_signal unmap;
 
-		struct wl_signal new_subsurface;
+		/**
+		 * Note: unlike other new_* signals, new_subsurface is emitted when
+		 * the subsurface is added to the parent surface's current state,
+		 * not when the object is created.
+		 */
+		struct wl_signal new_subsurface; // struct wlr_subsurface
 		struct wl_signal destroy;
 	} events;
 

types/wlr_subcompositor.c

@@ -289,6 +289,8 @@ void subsurface_handle_parent_commit(struct wlr_subsurface *subsurface) {
 
 	if (!subsurface->added) {
 		subsurface->added = true;
+		wl_signal_emit_mutable(&subsurface->parent->events.new_subsurface,
+			subsurface);
 		subsurface_consider_map(subsurface);
 	}
 }
@@ -362,8 +364,6 @@ static void subcompositor_handle_get_subsurface(struct wl_client *client,
 	wl_list_init(&subsurface->current.link);
 	wl_list_insert(parent->pending.subsurfaces_above.prev,
 		&subsurface->pending.link);
-
-	wl_signal_emit_mutable(&subsurface->parent->events.new_subsurface, subsurface);
 }
 
 static const struct wl_subcompositor_interface subcompositor_impl = {