Add some additional commenting around iothreads

src/iothread.h

@@ -31,11 +31,16 @@ int iothread_perform_impl(std::function<void(void)> &&func,
                           std::function<void(void)> &&completion);
 
 // Template helpers
+// This is the glue part of the handler-completion handoff
+// In general we can just allocate an object, move the result of the handler into it,
+// and then call the completion with that object. However if our type is void,
+// this won't work (new void() fails!). So we have to use this template.
+// The type T is the return type of HANDLER and the argument to COMPLETION
 template<typename T>
 struct _iothread_trampoline {
     template<typename HANDLER, typename COMPLETION>
     static int perform(const HANDLER &handler, const COMPLETION &completion) {
-        T *result = new T();
+        T *result = new T(); // TODO: placement new?
         return iothread_perform_impl([=](){ *result = handler(); },
                                      [=](){ completion(std::move(*result)); delete result; });
     }
@@ -53,6 +58,8 @@ struct _iothread_trampoline<void> {
 
 // iothread_perform invokes a handler on a background thread, and then a completion function
 // on the main thread. The value returned from the handler is passed to the completion.
+// In other words, this is like COMPLETION(HANDLER()) except the handler part is invoked
+// on a background thread.
 template<typename HANDLER, typename COMPLETION>
 int iothread_perform(const HANDLER &handler, const COMPLETION &completion) {
     return _iothread_trampoline<decltype(handler())>::perform(handler, completion);