Update C++ API comments to be more Doxygen friendly.

This patch:
- Updates // comments to ///. I manually reverted some comments that shouldn't be docs (e.g. TODOs), but may have missed some.
- Indents code blocks so they get formatted as such in the docs.
- Removes /* */ comments from example code since it messes up Doxygen.
- Puts a space between {{ and }} since it messes up devsite.
- Adds some // START_SKIP_DOXYGEN and // END_SKIP_DOXYGEN comments for functions that aren't part of the public API (incomplete)

This will likely require further small fixups, but this gets something to be generated.
Change: 144749351

2 files changed, 57 insertions, 57 deletions

diff --git a/tensorflow/cc/training/coordinator.h b/tensorflow/cc/training/coordinator.h
index 58e95f40f6..dbcf072015 100644
--- a/tensorflow/cc/training/coordinator.h
+++ b/tensorflow/cc/training/coordinator.h
@@ -28,77 +28,77 @@ limitations under the License.
 
 namespace tensorflow {
 
-// The abstract interface for runners which must implement the Join function.
+/// The abstract interface for runners which must implement the Join function.
 class RunnerInterface {
  public:
   virtual ~RunnerInterface() {}
   virtual Status Join() = 0;
 
-  // Returns true iff the runner is running, i.e. if it is trying to populate
-  // its queue.
+  /// Returns true iff the runner is running, i.e. if it is trying to populate
+  /// its queue.
   virtual bool IsRunning() const = 0;
 };
 
-// Coordinator class manages the termination of a collection of QueueRunners.
-// Without a coordinator, QueueRunners have to be joined in a specific order;
-// otherwise the QueueRunner::Join() could sometimes hang. The
-// Coordinator::RequestStop() plays the key role which notifies all running
-// threads under a coordinator to stop. This function could be called by any
-// thread or any client.
-// Usage, in the client:
-//   Coordinator coord;
-//   std::unique_ptr<QueueRunner> qr(&coord, ...);
-//   qr.Start(session);
-//   coord.RegisterRunner(std::move(qr));
-//   // do some work
-//   TF_CHECK_OK(coord.Join());
-// In each thread of QueueRunner, the coordinator needs to be used as:
-//   void Run() {
-//     while (!coord->ShouldStop()) {
-//       // do some work
-//       if (error) {
-//         coord->RequestStop();
-//         coord->ReportStatus(error_status);
-//       }
-//     }
-//   }
+/// Coordinator class manages the termination of a collection of QueueRunners.
+/// Without a coordinator, QueueRunners have to be joined in a specific order;
+/// otherwise the QueueRunner::Join() could sometimes hang. The
+/// Coordinator::RequestStop() plays the key role which notifies all running
+/// threads under a coordinator to stop. This function could be called by any
+/// thread or any client.
+/// Usage, in the client:
+///   Coordinator coord;
+///   std::unique_ptr<QueueRunner> qr(&coord, ...);
+///   qr.Start(session);
+///   coord.RegisterRunner(std::move(qr));
+///   /// do some work
+///   TF_CHECK_OK(coord.Join());
+/// In each thread of QueueRunner, the coordinator needs to be used as:
+///   void Run() {
+///     while (!coord->ShouldStop()) {
+///       /// do some work
+///       if (error) {
+///         coord->RequestStop();
+///         coord->ReportStatus(error_status);
+///       }
+///     }
+///   }
 class Coordinator {
  public:
   Coordinator();
 
-  // Constructor with a list of error codes which would not be taken as errors
-  // in status reporting.
+  /// Constructor with a list of error codes which would not be taken as errors
+  /// in status reporting.
   Coordinator(const std::vector<error::Code>& clean_stop_errors);
 
-  // In the destructor, RequestStop() and Join() would be called.
+  /// In the destructor, RequestStop() and Join() would be called.
   ~Coordinator();
 
-  // Registers a runner, i.e. a unit of running threads which is usually a
-  // QueueRunner. It takes the ownership of runner to avoid lifecycle-related
-  // problems. Note, the coordinator would not start these threads; they are
-  // supposed to be in running state when they are registered here.
+  /// Registers a runner, i.e. a unit of running threads which is usually a
+  /// QueueRunner. It takes the ownership of runner to avoid lifecycle-related
+  /// problems. Note, the coordinator would not start these threads; they are
+  /// supposed to be in running state when they are registered here.
   Status RegisterRunner(std::unique_ptr<RunnerInterface> runner);
 
-  // Returns true iff all the registered runners have been stopped.
+  /// Returns true iff all the registered runners have been stopped.
   bool AllRunnersStopped();
 
-  // Requests all running threads to stop.
+  /// Requests all running threads to stop.
   Status RequestStop();
 
-  // Returns true if its RequestStop() has been called.
+  /// Returns true if its RequestStop() has been called.
   bool ShouldStop();
 
-  // Joins all threads, returns OK or the first reported and unexpected status.
+  /// Joins all threads, returns OK or the first reported and unexpected status.
   Status Join();
 
-  // Reports status to the coordinator. This is usually called by threads.
+  /// Reports status to the coordinator. This is usually called by threads.
   void ReportStatus(const Status& status);
 
-  // Returns the latest status.
+  /// Returns the latest status.
   Status GetStatus();
 
-  // Returns immediately if the coordinator is stopped or blocks until
-  // RequestStop() is called.
+  /// Returns immediately if the coordinator is stopped or blocks until
+  /// RequestStop() is called.
   void WaitForStop();
 
  private:
diff --git a/tensorflow/cc/training/queue_runner.h b/tensorflow/cc/training/queue_runner.h
index e5aae8219f..bfe6a30593 100644
--- a/tensorflow/cc/training/queue_runner.h
+++ b/tensorflow/cc/training/queue_runner.h
@@ -32,46 +32,46 @@ limitations under the License.
 
 namespace tensorflow {
 
-// QueueRunner class imitates the behavior of the python version of QueueRunner
-// which creates a thread for each enqueue op, runs close op on completion.
+/// QueueRunner class imitates the behavior of the python version of QueueRunner
+/// which creates a thread for each enqueue op, runs close op on completion.
 class QueueRunner : public RunnerInterface {
  public:
-  // Creates a new QueueRunner from proto.
+  /// Creates a new QueueRunner from proto.
   // TODO(yuefengz): we may want to initialize from queues and ops in the
   // future.
   static Status New(const QueueRunnerDef& queue_runner_def,
                     std::unique_ptr<QueueRunner>* result);
 
-  // Creates a new QueueRunner with a coordinator, see coordinator.h for usage.
+  /// Creates a new QueueRunner with a coordinator, see coordinator.h for usage.
   static Status New(const QueueRunnerDef& queue_runner_def, Coordinator* coord,
                     std::unique_ptr<QueueRunner>* result);
 
-  // Adds a callback that the queue runner will call when it detects an error.
+  /// Adds a callback that the queue runner will call when it detects an error.
   void AddErrorCallback(const std::function<void(Status)>& cb);
 
-  // Delete the previously registered callbacks.
+  /// Delete the previously registered callbacks.
   void ClearErrorCallbacks();
 
-  // The destructor would join all the threads.
+  /// The destructor would join all the threads.
   ~QueueRunner();
 
-  // Starts the queue runner with the given session.
+  /// Starts the queue runner with the given session.
   Status Start(Session* sess);
 
-  // Starts the queue runner with the given session, and wait for up to the
-  // specified time (in milliseconds) for the queues to start to fill up.
+  /// Starts the queue runner with the given session, and wait for up to the
+  /// specified time (in milliseconds) for the queues to start to fill up.
   Status Start(Session* sess, int wait_for_ms);
 
-  // Requests to stop and runs the cancel op. It would be called in a separate
-  // thread when coordinator is set. If there is no coordinator it should be
-  // called before calling Join.
+  /// Requests to stop and runs the cancel op. It would be called in a separate
+  /// thread when coordinator is set. If there is no coordinator it should be
+  /// called before calling Join.
   void Stop(Session* sess);
 
-  // Joins all the threads. Returns okay if all threads run successfully;
-  // otherwise returns the first captured failure status.
+  /// Joins all the threads. Returns okay if all threads run successfully;
+  /// otherwise returns the first captured failure status.
   Status Join() final;
 
-  // Returns the latest status.
+  /// Returns the latest status.
   Status GetStatus();
 
  private: