Clean up formatting to simplify post-Doxygen processing.

ppapi/cpp/message_loop.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef PPAPI_CPP_MESSAGE_LOOP_H_
 #define PPAPI_CPP_MESSAGE_LOOP_H_
 
 #include "ppapi/cpp/resource.h"
 
+/// @file
+/// This file defines the PPB_MessageLoop API, which is used to allow
+/// PPAPI calls from any thread

[dmichael (off chromium), 2013/05/30 22:35:33]

nit: I'd just leave off the ", which is used..." part and add a period.

[Andy, 2013/05/30 22:49:05]

Done.

+
 namespace pp {
 
 class CompletionCallback;
 class InstanceHandle;
 
 /// A message loop allows PPAPI calls to be issued on a thread. You may not
 /// issue any API calls on a thread without creating a message loop. It also
 /// allows you to post work to the message loop for a thread.
 ///
 /// To process work posted to the message loop, as well as completion callbacks
@@ skipping 12 matching lines @@
 ///    - Create the thread yourself (using pthreads).
 ///    - Create the message loop resource.
 ///    - Pass the message loop resource to your thread's main function.
 ///    - Call PostWork() on the message loop to run functions on the thread.
 ///
 ///   From the background thread's main function:
 ///    - Call AttachToCurrentThread() with the message loop resource.
 ///    - Call Run() with the message loop resource.
 ///
 ///   Your callbacks should look like this:
-///      void DoMyWork(void* user_data, int32_t status) {
-///        if (status != PP_OK) {
-///          Cleanup();  // e.g. free user_data.
-///          return;
-///        }
-///        ... do your work...
-///      }
+///   @code
+///   void DoMyWork(void* user_data, int32_t status) {
+///     if (status != PP_OK) {
+///       Cleanup();  // e.g. free user_data.
+///       return;
+///     }
+///     ... do your work...
+///   }
+///   @endcode
 /// For a C++ example, see ppapi/utility/threading/simple_thread.h
 ///
 /// (You can also create the message loop resource on the background thread,
 /// but then the main thread will have no reference to it should you want to
 /// call PostWork()).
 ///
 ///
 /// THREAD HANDLING
 ///
 /// The main thread has an implicitly created message loop. The main thread is
@@ skipping 50 matching lines @@
 ///
 /// If you post a callback to a message loop that's been destroyed, or to an
 /// invalid message loop, PostWork will return an error and will not run the
 /// callback. This is true even for callbacks with the "required" flag set,
 /// since the system may not even know what thread to issue the error callback
 /// on.
 ///
 /// Therefore, you should check for errors from PostWork and destroy any
 /// associated memory to avoid leaks. If you're using the C++
 /// CompletionCallbackFactory, use the following pattern:
-///
-///   pp::CompletionCallback callback = factory_.NewOptionalCallback(...);
-///   int32_t result = message_loop.PostWork(callback);
-///   if (result != PP_OK)
-///     callback.Run(result);
-///
+/// @code
+/// pp::CompletionCallback callback = factory_.NewOptionalCallback(...);
+/// int32_t result = message_loop.PostWork(callback);
+/// if (result != PP_OK)
+///   callback.Run(result);
+/// @endcode
 /// This will run the callback with an error value, and assumes that the
 /// implementation of your callback checks the "result" argument and returns
 /// immediately on error.
 class MessageLoop : public Resource {
  public:
   /// Creates an is_null() MessageLoop resource.
   MessageLoop();
 
   /// Creates a message loop associated with the given instance. The resource
   /// will be is_null() on failure.
@@ skipping 119 matching lines @@
   ///   - PP_ERROR_BADRESOURCE: The message loop was invalid.
   ///   - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread.
   ///     The main thread's message loop is managed by the system and can't be
   ///     quit.
   int32_t PostQuit(bool should_destroy);
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_MESSAGE_LOOP_H_