Update docstring of executor classes per Mike's comment

include/aikido/util/ExecutorMultiplexer.hpp

@@ -8,7 +8,12 @@
 namespace aikido {
 namespace util {
 
-/// ExecutorMultiplexer stores callbacks and calls them in order of they added.
+/// Combine multiple executors (i.e. no argument callbacks) into one executor.
+///
+/// This helper class allows one ExecutorThread to call multiple executors by
+/// sequentially calling the callbacks added to this class.
+///
+/// \sa ExecutorThread
 class ExecutorMultiplexer final
 {
 public:
@@ -18,7 +23,11 @@ class ExecutorMultiplexer final
   /// Default destructor.
   ~ExecutorMultiplexer() = default;
 
-  /// Adds callback. The added callbacks will be called order of they added.
+  /// Adds a callback. The added callbacks will be called by operator().
+  ///
+  /// The order of callback calling is implementation detail that is subject to
+  /// change.
+  ///
   /// \param[in] callback Any callable object that doesn't return and take any
   /// parameters.
   void addCallback(std::function<void ()> callback);

include/aikido/util/ExecutorThread.hpp

@@ -12,14 +12,19 @@ namespace util {
 /// ExecutorThread is a wrapper of std::thread that calls a callback
 /// periodically.
 ///
+/// If you want to let ExecutorThread calls multiple callbacks then consider
+/// using ExecutorMultiplexer.
+///
 /// \code
 /// ExecutorThread exec(
-///     []() { std::cout << "running\n";}, std::chrono::nanoseconds(1));
+///     []() { std::cout << "running...\n"; }, std::chrono::milliseconds(10));
 ///
 /// // thread is running
 ///
-/// exec.stop();
+/// // The destructor of ExecutorThread stops the thread.
 /// \endcode
+///
+/// \sa ExecutorMultiplexer
 class ExecutorThread final
 {
 public:

tests/util/test_Executor.cpp

@@ -48,6 +48,9 @@ TEST(ExecutorThread, ExceptionThrownByCallback)
   ExecutorThread exec(
       []() { throw std::exception(); }, std::chrono::milliseconds(1));
 
+  // Assumed that the 3 second sleep is essentially a timeout for the test. If
+  // this is not the case, either increase the sleep time or remove this test
+  // (unless there is a better test for this).
   std::this_thread::sleep_for(std::chrono::seconds(3));
 
   EXPECT_TRUE(!exec.isRunning());