-In this class of Xapp the user simply provides a function that gets invoked, and typically that function has a `while (something)` in it.
-If the function returns, the Xapp will stop.
-In this type of Xapp, the Xapp must "pull" it's own data, typically from SDL, rmr (ie query another component for data), or other sources.
-The framework is "lighter" in this case then the former; it sets up an SDL connection, an rmr thread, and then calls the client provided function.
-This is to be used for Xapps that are not purely event driven.
-
-RMR Threading in the framework
-------------------------------
-NOTE: this is an implementation detail!
-We expose this for transparency but most users will not have to worry about this.
-
-In both types of Xapp, the framework launches a seperate thread whose only job is to read from rmr and deposit all messages (and their summaries) into a thread safe queue.
-When the client Xapp reads using the framework (this read is done by the framework itself in the RMR Xapp, but by the client in a general Xapp), the read is done from the queue.
-The framework is implemented this way so that a long running client function (e.g., consume) cannot block rmr reads.
-This is important because rmr is *not* a persistent message bus, if any rmr client does not read "fast enough", messages can be lost.
-So in this framework the client code is not in the same thread as the rmr reads, so that long running client code can never lead to lost messages.
-
-In the case of RMR Xapps, there are currently 3 potential threads; the thread that reads from rmr directly, and the user can optionally have the rmr queue read run in a thread, returning execution back to the user thread.
-The default is only two threads however, where `.run` does not return back execution and the user code is "finished" at that point.
+
+A general Xapp acts according to its own criteria, which may include
+receipt of RMR messages.
+
+This type of application is constructed by creating a single function
+that is invoked by the framework after initialization. Typically that
+function contains a `while (something)` event loop. When the function
+returns, the Xapp stops. In this usage, the Xapp must fetch its own
+data, either from RMR, SDL or other source. The framework does less
+work for a general application compared to a reactive application; the
+framework only sets up an RMR thread and an SDL connection before
+invoking the client-provided function.
+
+Threading in the Framework
+--------------------------
+
+RMR interactions are processed in a thread started by the framework.
+This implementation detail is documented here for transparency, but
+most users will not have to worry about this.
+
+In both types of Xapp, the framework launches a separate thread whose
+only job is to read from RMR and deposit all messages (and their
+summaries) into a thread-safe queue. When the client Xapp reads from
+RMR using the framework (this read is done by the framework itself in
+the RMR Xapp, but by the client in a general Xapp), the read is done
+from the framework-managed queue. The framework is implemented this
+way so that a long-running client function (e.g., consume) will not
+block RMR reads. This is important because RMR is *not* a persistent
+message bus; if an RMR client does not read fast enough, messages can
+be lost. So in this framework the client code is not in the same
+thread as the RMR reads, to ensure that long-running client code will
+not cause message loss.
+
+In the case of RMR Xapps, there are currently 3 potential threads; the
+thread that reads from RMR directly, and the user can optionally have
+the RMR queue read run in a thread, returning execution back to the
+user thread. The default is only two threads however, where `.run`
+does not return back execution and the user code is finished at that
+point.