Comment some of the callback-related code

Some of the code dealing with callbacks and updates was a little
obscure. A few extra comments should help clarify the meaning.

src/common.cc

@@ -275,15 +275,13 @@ conky::simple_config_setting<bool> no_buffers("no_buffers", true, true);
 
 void update_stuff(void)
 {
-	int i;
-
 	/* clear speeds, addresses and up status in case device was removed and
 	 *  doesn't get updated */
 
 	#ifdef HAVE_OPENMP
 	#pragma omp parallel for schedule(dynamic,10)
 	#endif /* HAVE_OPENMP */
-	for (i = 0; i < MAX_NET_INTERFACES; i++) {
+	for (int i = 0; i < MAX_NET_INTERFACES; ++i) {
 		if (netstats[i].dev) {
 			netstats[i].up = 0;
 			netstats[i].recv_speed = 0.0;
@@ -295,8 +293,10 @@ void update_stuff(void)
 		}
 	}
 
+	/* this is a stub on all platforms except solaris */
 	prepare_update();
 
+	/* if you registered a callback with conky::register_cb, this will run it */
 	conky::run_all_callbacks();
 
 	/* XXX: move the following into the update_meminfo() functions? */

src/conky.cc

@@ -909,19 +909,17 @@ static void generate_text(void)
 {
 	char *p;
 	unsigned int i, j, k;
-
 	special_count = 0;
 
-	/* update info */
-
 	current_update_time = get_time();
 
+	/* clears netstats info, calls conky::run_all_callbacks(), and changes
+	 * some info.mem entries */
 	update_stuff();
 
-	/* add things to the buffer */
-
-	/* generate text */
-
+	/* populate the text buffer; generate_text_internal() iterates through
+	 * global_root_object (an instance of the text_object struct) and calls
+	 * any callbacks that were set on startup by construct_text_object(). */
 	p = text_buffer;
 
 	generate_text_internal(p, max_user_text.get(*state), global_root_object);

src/update-cb.cc

@@ -77,6 +77,12 @@ namespace conky {
 			return *a == *b;
 		}
 
+		/*
+		 * If a callback is not successfully inserted into the set, it must have
+		 * the same hash as an existing callback. If this is so, merge the incoming
+		 * callback with the one that prevented insertion. Keep the smaller of the
+		 * two periods.
+		 */
 		void callback_base::merge(callback_base &&other)
 		{
 			if(other.period < period) {
@@ -87,10 +93,14 @@ namespace conky {
 			unused = 0;
 		}
 
+		/*
+		 * Register a callback (i.e. insert it into the callbacks set)
+		 */
 		callback_base::handle callback_base::do_register_cb(const handle &h)
 		{
 			const auto &p = callbacks.insert(h);
 
+			/* insertion failed; callback already exists */
 			if(not p.second)
 				(*p.first)->merge(std::move(*h));
 
@@ -134,7 +144,10 @@ namespace conky {
 		for(auto i = callback_base::callbacks.begin(); i != callback_base::callbacks.end(); ) {
 			callback_base &cb = **i;
 
+			/* check whether enough update intervals have elapsed (up to period) */
 			if(cb.remaining-- == 0) {
+				/* run the callback as long as someone holds a pointer to it;
+				 * if no one owns the callback, run it at most UNUSED_MAX times */
 				if(!i->unique() || ++cb.unused < UNUSED_MAX) {
 					cb.remaining = cb.period-1;
 					cb.run();

src/update-cb.hh

@@ -56,13 +56,13 @@ namespace conky {
 
 			semaphore sem_start;
 			std::thread *thread;
-			const size_t hash;
-			uint32_t period;
-			uint32_t remaining;
+			const size_t hash;		/* used to determined callback uniqueness */
+			uint32_t period;		/* how often to run a callback */
+			uint32_t remaining;		/* update intervals remaining until we can run a callback */
 			std::pair<int, int> pipefd;
-			const bool wait;
-			bool done;
-			uint8_t unused;
+			const bool wait;		/* whether or not to wait for a callback to finish */
+			bool done;			/* if true, callback is being stopped and destroyed */
+			uint8_t unused;			/* number of update intervals during which no one owns a callback */
 
 			callback_base(const callback_base &) = delete;
 			callback_base& operator=(const callback_base &) = delete;
@@ -159,6 +159,9 @@ namespace conky {
 				));
 	}
 
+	/*
+	 * Callback uniqueness is determined by the hash computed here.
+	 */
 	namespace priv {
 		template<size_t pos, typename... Elements>
 		struct hash_tuple {