added comments

doc/MISC.md

@@ -6,8 +6,10 @@ A binary tree is *full* if each of its node has either two or zero children.
 
 If a node has two children it is an internal node, otherwise a leaf.
 
-Fundamental theorem:
-Let I be the number of internal nodes and L the number of leaves, then:
+## Fundamental theorem:
+
+*Let `I` be the number of internal nodes and `L` the number of leaves, then:*
+
 	L = I + 1
 
 (It can be proved by induction on the number of internal nodes.)

examples/bspwmrc

@@ -1,16 +1,24 @@
 #! /bin/sh
 
+# restart sxhkd
 pgrep -x sxhkd > /dev/null || sxhkd &
 
+# define the virtual desktops
 bspc monitor -d I II III IV V VI VII VIII IX X
 
+# window border width 
 bspc config border_width         2
+# gap between tiled windows
 bspc config window_gap          12
 
+# where should a window split upon launching a new application (0.5 == split in half)
 bspc config split_ratio          0.52
+# Remove borders of tiled windows for the monocle desktop layout.
 bspc config borderless_monocle   true
+# Remove gaps of tiled windows for the monocle desktop layout.
 bspc config gapless_monocle      true
 
+# add rules to specific windows
 bspc rule -a Gimp desktop='^8' state=floating follow=on
 bspc rule -a Chromium desktop='^2'
 bspc rule -a mplayer2 state=floating

src/bspc.c

@@ -35,17 +35,25 @@
 
 int main(int argc, char *argv[])
 {
+	// Holds the socket file descriptor
 	int sock_fd;
+	// The address of the AF_LOCAL (aka AF_UNIX) socket
 	struct sockaddr_un sock_address;
-	char msg[BUFSIZ], rsp[BUFSIZ];
+	// Holds the message to send to bspwm
+	char msg[BUFSIZ];
+	// Holds the received response from bspwm
+	char rsp[BUFSIZ];
 
 	if (argc < 2) {
 		err("No arguments given.\n");
 	}
 
+	// TODO: describe what this does
 	sock_address.sun_family = AF_UNIX;
+	// TODO: what does sp stand for? sun path?
 	char *sp;
 
+	// Try to open a socket connection
 	if ((sock_fd = socket(AF_UNIX, SOCK_STREAM, 0)) == -1) {
 		err("Failed to create the socket.\n");
 	}
@@ -62,50 +70,70 @@ int main(int argc, char *argv[])
 		free(host);
 	}
 
+	// try to connect to the socket
 	if (connect(sock_fd, (struct sockaddr *) &sock_address, sizeof(sock_address)) == -1) {
 		err("Failed to connect to the socket.\n");
 	}
 
 	argc--, argv++;
+	// Length of the message to send to bspwm
 	int msg_len = 0;
 
+	// calculate the message length
 	for (int offset = 0, rem = sizeof(msg), n = 0; argc > 0 && rem > 0; offset += n, rem -= n, argc--, argv++) {
 		n = snprintf(msg + offset, rem, "%s%c", *argv, 0);
 		msg_len += n;
 	}
 
+	// Send the message to the socket
 	if (send(sock_fd, msg, msg_len, 0) == -1) {
 		err("Failed to send the data.\n");
 	}
 
-	int ret = EXIT_SUCCESS, nb;
+	// The return code to send back to the process bspc is called from
+	int ret = EXIT_SUCCESS;
+	// Holds the number of bytes received
+	int nb;
 
+	// the set of file descriptors to be polled
 	struct pollfd fds[] = {
 		{sock_fd, POLLIN, 0},
 		{STDOUT_FILENO, POLLHUP, 0},
 	};
 
+	// while at least one of the 2 descriptors return events (0 == timeout, -1 == error)
 	while (poll(fds, 2, -1) > 0) {
+		// if bspc receives data from bspwm
 		if (fds[0].revents & POLLIN) {
+			// if the number of received bytes > 0, store the response in rsp
 			if ((nb = recv(sock_fd, rsp, sizeof(rsp)-1, 0)) > 0) {
+				// add a null termintor to the end of the response
 				rsp[nb] = '\0';
+				// if bspwm responds with a failure message
 				if (rsp[0] == FAILURE_MESSAGE[0]) {
+					// change the return code
 					ret = EXIT_FAILURE;
+					// print the error (to stderr)
 					fprintf(stderr, "%s", rsp + 1);
 					fflush(stderr);
 				} else {
+					// print the response (to stdout)
 					fprintf(stdout, "%s", rsp);
 					fflush(stdout);
 				}
 			} else {
+				// if bspwm responds, stop polling
 				break;
 			}
 		}
 		if (fds[1].revents & (POLLERR | POLLHUP)) {
+			// stop polling if stdout is closed
 			break;
 		}
 	}
 
+	// close the socket
 	close(sock_fd);
+	// return 
 	return ret;
 }