More trivial cleanupi of ppapi/c/trusted headers

ppapi/c/trusted/ppb_file_io_trusted.h

Index: ppapi/c/trusted/ppb_file_io_trusted.h
===================================================================
--- ppapi/c/trusted/ppb_file_io_trusted.h	(revision 92804)
+++ ppapi/c/trusted/ppb_file_io_trusted.h	(working copy)
@@ -2,47 +2,68 @@
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
-#ifndef PPAPI_C_PPB_FILE_IO_TRUSTED_H_
-#define PPAPI_C_PPB_FILE_IO_TRUSTED_H_
 
+/* From trusted/ppb_file_io_trusted.idl modified Mon Jul 18 10:45:10 2011. */
+
+#ifndef PPAPI_C_TRUSTED_PPB_FILE_IO_TRUSTED_H_
+#define PPAPI_C_TRUSTED_PPB_FILE_IO_TRUSTED_H_
+
+#include "ppapi/c/pp_completion_callback.h"
+#include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
 
-struct PP_CompletionCallback;
+/**
+ * @file
+ *
+ * This file defines the trusted file IO interface
+ */
 
+
+/**
+ * @addtogroup Interfaces
+ * @{
+ */
+/* Available only to trusted implementations. */
 #define PPB_FILEIOTRUSTED_INTERFACE_0_4 "PPB_FileIOTrusted;0.4"
 #define PPB_FILEIOTRUSTED_INTERFACE PPB_FILEIOTRUSTED_INTERFACE_0_4
 
-// Available only to trusted implementations.
 struct PPB_FileIOTrusted {
-  // Returns a file descriptor corresponding to the given FileIO object. On
-  // Windows, returns a HANDLE; on all other platforms, returns a POSIX file
-  // descriptor. The FileIO object must have been opened with a successful
-  // call to FileIO::Open.  The file descriptor will be closed automatically
-  // when the FileIO object is closed or destroyed.
+  /**
+   * Returns a file descriptor corresponding to the given FileIO object. On
+   * Windows, returns a HANDLE; on all other platforms, returns a POSIX file
+   * descriptor. The FileIO object must have been opened with a successful
+   * call to FileIO::Open.  The file descriptor will be closed automatically
+   * when the FileIO object is closed or destroyed.
+   */
   int32_t (*GetOSFileDescriptor)(PP_Resource file_io);
-
-  // Notifies the browser that underlying file will be modified.  This gives
-  // the browser the opportunity to apply quota restrictions and possibly
-  // return an error to indicate that the write is not allowed.
+  /**
+   * Notifies the browser that underlying file will be modified.  This gives
+   * the browser the opportunity to apply quota restrictions and possibly
+   * return an error to indicate that the write is not allowed.
+   */
   int32_t (*WillWrite)(PP_Resource file_io,
                        int64_t offset,
                        int32_t bytes_to_write,
                        struct PP_CompletionCallback callback);
-
-  // Notifies the browser that underlying file will be modified.  This gives
-  // the browser the opportunity to apply quota restrictions and possibly
-  // return an error to indicate that the write is not allowed.
+  /**
+   * Notifies the browser that underlying file will be modified.  This gives
+   * the browser the opportunity to apply quota restrictions and possibly
+   * return an error to indicate that the write is not allowed.
+   *
+   * TODO(darin): Maybe unify the above into a single WillChangeFileSize
+   * method?  The above methods have the advantage of mapping to PPB_FileIO
+   * Write and SetLength calls.  WillChangeFileSize would require the caller to
+   * compute the file size resulting from a Write call, which may be
+   * undesirable.
+   */

[dmichael (off chromium), 2011/07/18 21:19:40]

Is there any way to have comments go in to a separate section that doesn't have
the doxygen style? Maybe even just the way you inject verbatim code or
something.

But in general I'd prefer not to have these TODOs show up in the doxygen output.

Feel free to do in another CL.

   int32_t (*WillSetLength)(PP_Resource file_io,
                            int64_t length,
                            struct PP_CompletionCallback callback);
-
-  // TODO(darin): Maybe unify the above into a single WillChangeFileSize
-  // method?  The above methods have the advantage of mapping to PPB_FileIO
-  // Write and SetLength calls.  WillChangeFileSize would require the caller to
-  // compute the file size resulting from a Write call, which may be
-  // undesirable.
 };
+/**
+ * @}
+ */
 
-#endif  /* PPAPI_C_PPB_FILE_IO_TRUSTED_H_ */
+#endif  /* PPAPI_C_TRUSTED_PPB_FILE_IO_TRUSTED_H_ */