Add comments to explain what's up

Author: emersion

main.c

@@ -32,6 +32,8 @@ static void noop() {
 
 static void xdg_wm_base_handle_ping(void *data,
 		struct xdg_wm_base *xdg_wm_base, uint32_t serial) {
+	// The compositor will send us a ping event to check that we're responsive.
+	// We need to send back a pong request immediately.
 	xdg_wm_base_pong(xdg_wm_base, serial);
 }
 
@@ -41,12 +43,17 @@ static const struct xdg_wm_base_listener xdg_wm_base_listener = {
 
 static void xdg_surface_handle_configure(void *data,
 		struct xdg_surface *xdg_surface, uint32_t serial) {
+	// The compositor configures our surface, acknowledge the configure event
 	xdg_surface_ack_configure(xdg_surface, serial);
+
 	if (configured) {
+		// If this isn't the first configure event we've received, we already
+		// have a buffer attached, so no need to do anything. Commit the
+		// surface to apply the configure acknowledgement.
 		wl_surface_commit(surface);
-	} else {
-		configured = true;
 	}
+
+	configured = true;
 }
 
 static const struct xdg_surface_listener xdg_surface_listener = {
@@ -55,6 +62,7 @@ static const struct xdg_surface_listener xdg_surface_listener = {
 
 static void xdg_toplevel_handle_close(void *data,
 		struct xdg_toplevel *xdg_toplevel) {
+	// Stop running if the user requests to close the toplevel
 	running = false;
 }
 
@@ -67,6 +75,8 @@ static void pointer_handle_button(void *data, struct wl_pointer *pointer,
 		uint32_t serial, uint32_t time, uint32_t button, uint32_t state) {
 	struct wl_seat *seat = data;
 
+	// If the user presses the left pointer button, start an interactive move
+	// of the toplevel
 	if (button == BTN_LEFT && state == WL_POINTER_BUTTON_STATE_PRESSED) {
 		xdg_toplevel_move(xdg_toplevel, seat, serial);
 	}
@@ -82,6 +92,8 @@ static const struct wl_pointer_listener pointer_listener = {
 
 static void seat_handle_capabilities(void *data, struct wl_seat *seat,
 		uint32_t capabilities) {
+	// If the wl_seat has the pointer capability, start listening to pointer
+	// events
 	if (capabilities & WL_SEAT_CAPABILITY_POINTER) {
 		struct wl_pointer *pointer = wl_seat_get_pointer(seat);
 		wl_pointer_add_listener(pointer, &pointer_listener, seat);
@@ -123,52 +135,59 @@ static struct wl_buffer *create_buffer(void) {
 	int stride = width * 4;
 	int size = stride * height;
 
+	// Allocate a shared memory file with the right size
 	int fd = create_shm_file(size);
 	if (fd < 0) {
 		fprintf(stderr, "creating a buffer file for %d B failed: %m\n", size);
 		return NULL;
 	}
 
+	// Map the shared memory file
 	shm_data = mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
 	if (shm_data == MAP_FAILED) {
 		fprintf(stderr, "mmap failed: %m\n");
 		close(fd);
 		return NULL;
 	}
 
+	// Create a wl_buffer from our shared memory file descriptor
 	struct wl_shm_pool *pool = wl_shm_create_pool(shm, fd, size);
 	struct wl_buffer *buffer = wl_shm_pool_create_buffer(pool, 0, width, height,
 		stride, WL_SHM_FORMAT_ARGB8888);
 	wl_shm_pool_destroy(pool);
 
-	// MagickImage is from cat.h
+	// Now that we've mapped the file and created the wl_buffer, we no longer
+	// need to keep file descriptor opened
+	close(fd);
+
+	// Copy pixels into our shared memory file (MagickImage is from cat.h)
 	memcpy(shm_data, MagickImage, size);
+
 	return buffer;
 }
 
 int main(int argc, char *argv[]) {
+	// Connect to the Wayland compositor
 	struct wl_display *display = wl_display_connect(NULL);
 	if (display == NULL) {
 		fprintf(stderr, "failed to create display\n");
 		return EXIT_FAILURE;
 	}
 
+	// Obtain the wl_registry and fetch the list of globals
 	struct wl_registry *registry = wl_display_get_registry(display);
 	wl_registry_add_listener(registry, &registry_listener, NULL);
 	if (wl_display_roundtrip(display) == -1) {
 		return EXIT_FAILURE;
 	}
 
+	// Check that all globals we require are available
 	if (shm == NULL || compositor == NULL || xdg_wm_base == NULL) {
 		fprintf(stderr, "no wl_shm, wl_compositor or xdg_wm_base support\n");
 		return EXIT_FAILURE;
 	}
 
-	struct wl_buffer *buffer = create_buffer();
-	if (buffer == NULL) {
-		return EXIT_FAILURE;
-	}
-
+	// Create a wl_surface, a xdg_surface and a xdg_toplevel
 	surface = wl_compositor_create_surface(compositor);
 	struct xdg_surface *xdg_surface =
 		xdg_wm_base_get_xdg_surface(xdg_wm_base, surface);
@@ -177,14 +196,22 @@ int main(int argc, char *argv[]) {
 	xdg_surface_add_listener(xdg_surface, &xdg_surface_listener, NULL);
 	xdg_toplevel_add_listener(xdg_toplevel, &xdg_toplevel_listener, NULL);
 
+	// Perform the initial commit and wait for the first configure event
 	wl_surface_commit(surface);
 	while (wl_display_dispatch(display) != -1 && !configured) {
 		// This space intentionally left blank
 	}
 
+	// Create a wl_buffer, attach it to the surface and commit the surface
+	struct wl_buffer *buffer = create_buffer();
+	if (buffer == NULL) {
+		return EXIT_FAILURE;
+	}
+
 	wl_surface_attach(surface, buffer, 0, 0);
 	wl_surface_commit(surface);
 
+	// Continue dispatching events until the user closes the toplevel
 	while (wl_display_dispatch(display) != -1 && running) {
 		// This space intentionally left blank
 	}