doc: Fix all Doxygen warnings, cleaning up some generated documentation

This makes Doxygen’s output more actionable by setting QUIET = YES to
suppress verbose progress spew, and WARN_IF_UNDOCUMENTED = NO to prevent
warnings for undocumented classes and members from being generated. The
latter is too noisy, producing 721 warnings in the current codebase.

The remaining warnings produced by Doxygen were useful and actionable.
They fell into two categories: abuses of Doxygen’s markup syntax, and
missing (or misspelled) parameter documentation. In a small number of
cases, pass-through parameters had intentionally been left undocumented.
In these cases, they are now given blank \param descriptions. This is
not optimal, but there doesn’t appear to be any other way to tell
Doxygen to allow a single parameter to be undocumented.

Some tricky Doxygen errors were resolved by asking it to not enter
directiores that we do not provide documentation in (such as the
“on-platform” compat directories, compat/mac and compat/win, as well as
compat/non_cxx11_lib) while allowing it to enter the
“off-platform” directories that we do document (compat/non_mac and
compat/non_win).

A Doxygen run (doc/support/generate_doxygen.sh) now produces no output
at all. It would produce warnings if any were triggered.

Not directly related, but still relevant to documentation,
doc/support/generate.sh is updated to remove temporary removals of
now-extinct files and directories. doc/appengine/README is updated so
that a consistent path to “goapp” is used throughout the file.

Change-Id: I300730c04de4d3340551ea3086ca70cc5ff862d1
Reviewed-on: https://chromium-review.googlesource.com/408812
Reviewed-by: Robert Sesek <rsesek@chromium.org>

client/crashpad_info.h

@@ -164,9 +164,9 @@ struct CrashpadInfo {
   //! \brief Adds a custom stream to the minidump.
   //!
   //! The memory block referenced by \a data and \a size will added to the
-  //! minidump as separate stream with type \stream_type. The memory referred to
+  //! minidump as separate stream with type \a stream_type. The memory referred
-  //! by \a data and \a size is owned by the caller and must remain valid while
+  //! to by \a data and \a size is owned by the caller and must remain valid
-  //! it is in effect for the CrashpadInfo object.
+  //! while it is in effect for the CrashpadInfo object.
   //!
   //! Note that streams will appear in the minidump in the reverse order to
   //! which they are added.

client/prune_crash_reports.h

@@ -111,7 +111,7 @@ class DatabaseSizePruneCondition final : public PruneCondition {
   DISALLOW_COPY_AND_ASSIGN(DatabaseSizePruneCondition);
 };
 
-//! \breif A PruneCondition that conjoins two other PruneConditions.
+//! \brief A PruneCondition that conjoins two other PruneConditions.
 class BinaryPruneCondition final : public PruneCondition {
  public:
   enum Operator {

compat/non_win/dbghelp.h

@@ -423,8 +423,8 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_EXCEPTION {
   //! the original exception code will appear instead. The exception type as it
   //! was received will appear at index 0 of #ExceptionInformation.
   //!
-  //! For Windows minidumps, this will be an \ref EXCEPTION_x "EXCEPTION_*"
+  //! For Windows minidumps, this will be an `EXCEPTION_*` exception type, such
-  //! exception type, such as `EXCEPTION_ACCESS_VIOLATION`.
+  //! as `EXCEPTION_ACCESS_VIOLATION`.
   //!
   //! \note This field is named ExceptionCode, but what is known as the
   //!     “exception code” on macOS/Mach is actually stored in the
@@ -982,8 +982,9 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_MEMORY_INFO {
 
   //! \brief The memory protection when the region was initially allocated. This
   //!     member can be one of the memory protection options (such as
-  //!     \ref PAGE_x PAGE_EXECUTE, \ref PAGE_x PAGE_NOACCESS, etc.), along with
+  //!     \ref PAGE_x "PAGE_EXECUTE", \ref PAGE_x "PAGE_NOACCESS", etc.), along
-  //!     \ref PAGE_x PAGE_GUARD or \ref PAGE_x PAGE_NOCACHE, as needed.
+  //!     with \ref PAGE_x "PAGE_GUARD" or \ref PAGE_x "PAGE_NOCACHE", as
+  //!     needed.
   uint32_t AllocationProtect;
 
   uint32_t __alignment1;
@@ -993,7 +994,8 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_MEMORY_INFO {
   uint64_t RegionSize;
 
   //! \brief The state of the pages in the region. This can be one of
-  //!     \ref MEM_x MEM_COMMIT, \ref MEM_x MEM_FREE, or \ref MEM_x MEM_RESERVE.
+  //!     \ref MEM_x "MEM_COMMIT", \ref MEM_x "MEM_FREE", or \ref MEM_x
+  //!     "MEM_RESERVE".
   uint32_t State;
 
   //! \brief The access protection of the pages in the region. This member is
@@ -1001,7 +1003,7 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_MEMORY_INFO {
   uint32_t Protect;
 
   //! \brief The type of pages in the region. This can be one of \ref MEM_x
-  //!     MEM_IMAGE, \ref MEM_x MEM_MAPPED, or \ref MEM_x MEM_PRIVATE.
+  //!     "MEM_IMAGE", \ref MEM_x "MEM_MAPPED", or \ref MEM_x "MEM_PRIVATE".
   uint32_t Type;
 
   uint32_t __alignment2;

doc/appengine/README

@@ -28,7 +28,7 @@ To deploy:
 
 $ version=$(git rev-parse --short=12 HEAD)
 $ [[ -n "$(git status --porcelain)" ]] && version+=-dirty
-$ goapp deploy -version "${version}"
+$ …/go_appengine/goapp deploy -version "${version}"
 
 Note that app.yaml does not name a “version” to encourage you to use a git hash
 as the version, as above.

doc/support/crashpad.doxy

@@ -162,7 +162,7 @@ STRIP_FROM_PATH        =
 # using the -I flag.
 
 STRIP_FROM_INC_PATH    = . \
-                         compat/mac \
+                         compat/non_mac \
                          compat/non_win
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
@@ -716,7 +716,7 @@ CITE_BIB_FILES         =
 # messages are off.
 # The default value is: NO.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES
@@ -732,7 +732,7 @@ WARNINGS               = YES
 # will automatically be disabled.
 # The default value is: YES.
 
-WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_UNDOCUMENTED   = NO
 
 # If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for
 # potential errors in the documentation, such as not documenting some parameters
@@ -826,7 +826,10 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                = third_party
+EXCLUDE                = compat/mac \
+                         compat/non_cxx11_lib \
+                         compat/win \
+                         third_party
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded

doc/support/generate.sh

@@ -37,10 +37,5 @@ maybe_mkdir "${output_dir}/doxygen"
 rsync -Ilr --delete --exclude .git "out/doc/doxygen/html/" \
     "${output_dir}/doxygen"
 
-# Remove old things that used to be present
-rm -rf "${output_dir}/doc"
-rm -rf "${output_dir}/man"
-rm -f "${output_dir}/index.html"
-
 # Ensure a favicon exists at the root since the browser will always request it.
 cp doc/favicon.ico "${output_dir}/"

minidump/minidump_extensions.h

@@ -276,7 +276,7 @@ struct ALIGNAS(4) PACKED MinidumpSimpleStringDictionary {
 //! #version, so that newer parsers will be able to determine whether the added
 //! fields are valid or not.
 //!
-//! \sa #MinidumpModuleCrashpadInfoList
+//! \sa MinidumpModuleCrashpadInfoList
 struct ALIGNAS(4) PACKED MinidumpModuleCrashpadInfo {
   //! \brief The structure’s currently-defined version number.
   //!
@@ -423,7 +423,7 @@ struct ALIGNAS(4) PACKED MinidumpCrashpadInfo {
   //! This field is present when #version is at least `1`.
   MINIDUMP_LOCATION_DESCRIPTOR simple_annotations;
 
-  //! \brief A pointer to a #MinidumpModuleCrashpadInfoList structure.
+  //! \brief A pointer to a MinidumpModuleCrashpadInfoList structure.
   //!
   //! This field is present when #version is at least `1`.
   MINIDUMP_LOCATION_DESCRIPTOR module_list;

minidump/minidump_module_crashpad_info_writer.h

@@ -125,11 +125,12 @@ class MinidumpModuleCrashpadInfoListWriter final
   //! \brief Adds a MinidumpModuleCrashpadInfo to the
   //!     MinidumpModuleCrashpadInfoList.
   //!
-  //! \param[in] module Extended Crashpad-specific information about the module.
+  //! \param[in] module_crashpad_info Extended Crashpad-specific information
-  //!     This object takes ownership of \a module and becomes its parent in the
+  //!     about the module. This object takes ownership of \a
-  //!     overall tree of internal::MinidumpWritable objects.
+  //!     module_crashpad_info and becomes its parent in the overall tree of
-  //! \param[in] module_list_index The index of the MINIDUMP_MODULE in the
+  //!     internal::MinidumpWritable objects.
-  //!     minidump file’s MINIDUMP_MODULE_LIST stream that corresponds to \a
+  //! \param[in] minidump_module_list_index The index of the MINIDUMP_MODULE in
+  //!     the minidump file’s MINIDUMP_MODULE_LIST stream that corresponds to \a
   //!     module_crashpad_info.
   //!
   //! \note Valid in #kStateMutable.

snapshot/capture_memory.h

@@ -71,8 +71,8 @@ class CaptureMemory {
   //! unsigned) so that there's a reasonable chance that the value is a pointer.
   //!
   //! \param[in] context The context to inspect.
-  //! \param[in] process_reader A MemoryCaptureProcessReader to read from the
+  //! \param[in] delegate A Delegate that handles reading from the target
-  //!     target process, and that handles adding new ranges.
+  //!     process and adding new ranges.
   static void PointedToByContext(const CPUContext& context, Delegate* delegate);
 
   //! \brief For all pointer-like values in a memory range of the target
@@ -83,8 +83,8 @@ class CaptureMemory {
   //!     base address and size must be pointer-aligned and an integral number
   //!     of
   //!     pointers long.
-  //! \param[in] process_reader A MemoryCaptureProcessReader to read from the
+  //! \param[in] delegate A Delegate that handles reading from the target
-  //!     target process, and that handles adding new ranges.
+  //!     process and adding new ranges.
   static void PointedToByMemoryRange(const MemorySnapshot& memory,
                                      Delegate* delegate);
 

snapshot/exception_snapshot.h

@@ -56,8 +56,8 @@ class ExceptionSnapshot {
   //! the original exception code will appear instead. The exception type as it
   //! was received will appear at index 0 of Codes().
   //!
-  //! For Windows, this will be an \ref EXCEPTION_x "EXCEPTION_*" exception type
+  //! For Windows, this will be an `EXCEPTION_*` exception type, such as
-  //! such as `EXCEPTION_ACCESS_VIOLATION`.
+  //! `EXCEPTION_ACCESS_VIOLATION`.
   virtual uint32_t Exception() const = 0;
 
   //! \brief Returns the second-level exception code identifying the exception.

snapshot/mac/exception_snapshot_mac.h

@@ -47,6 +47,14 @@ class ExceptionSnapshotMac final : public ExceptionSnapshot {
   //!
   //! \param[in] process_reader A ProcessReader for the task that sustained the
   //!     exception.
+  //! \param[in] behavior
+  //! \param[in] exception_thread
+  //! \param[in] exception
+  //! \param[in] code
+  //! \param[in] code_count
+  //! \param[in,out] flavor
+  //! \param[in] state
+  //! \param[in] state_count
   //!
   //! \return `true` if the snapshot could be created, `false` otherwise with
   //!     an appropriate message logged.

snapshot/mac/process_reader.h

@@ -191,18 +191,18 @@ class ProcessReader {
   //! tag value. If these conditions cannot be met fully, as much of the red
   //! zone will be captured as is possible while meeting these conditions.
   //!
-  //! \param[inout] start_address The base address of the region to begin
+  //! \param[in,out] start_address The base address of the region to begin
   //!     capturing stack memory from. On entry, \a start_address is the stack
   //!     pointer. On return, \a start_address may be decreased to encompass a
   //!     red zone.
-  //! \param[inout] region_base The base address of the region that contains
+  //! \param[in,out] region_base The base address of the region that contains
   //!     stack memory. This is distinct from \a start_address in that \a
   //!     region_base will be page-aligned. On entry, \a region_base is the
   //!     base address of a region that contains \a start_address. On return,
   //!     if \a start_address is decremented and is outside of the region
   //!     originally described by \a region_base, \a region_base will also be
   //!     decremented appropriately.
-  //! \param[inout] region_size The size of the region that contains stack
+  //! \param[in,out] region_size The size of the region that contains stack
   //!     memory. This region begins at \a region_base. On return, if \a
   //!     region_base is decremented, \a region_size will be incremented
   //!     appropriately.

snapshot/mac/process_types/custom.cc

@@ -21,6 +21,8 @@
 #include "snapshot/mac/process_types/internal.h"
 #include "util/mach/task_memory.h"
 
+#if !DOXYGEN
+
 namespace crashpad {
 namespace process_types {
 namespace internal {
@@ -157,3 +159,5 @@ bool crashreporter_annotations_t<Traits>::ReadInto(
 }  // namespace internal
 }  // namespace process_types
 }  // namespace crashpad
+
+#endif  // !DOXYGEN

snapshot/system_snapshot.h

@@ -104,7 +104,7 @@ class SystemSnapshot {
   virtual std::string CPUVendor() const = 0;
 
   //! \brief Returns frequency information about the snapshot system’s CPUs in
-  //!     \current_hz and \a max_hz.
+  //!     \a current_hz and \a max_hz.
   //!
   //! \param[out] current_hz The snapshot system’s CPU clock frequency in Hz at
   //!     the time of the snapshot.
@@ -258,7 +258,7 @@ class SystemSnapshot {
   //!     being observed.
   //! \param[out] daylight_name The name of the time zone while daylight saving
   //!     time is being observed.
-  virtual void TimeZone(DaylightSavingTimeStatus* observes_daylight,
+  virtual void TimeZone(DaylightSavingTimeStatus* dst_status,
                         int* standard_offset_seconds,
                         int* daylight_offset_seconds,
                         std::string* standard_name,

snapshot/test/test_process_snapshot.h

@@ -121,7 +121,7 @@ class TestProcessSnapshot final : public ProcessSnapshot {
 
   //! \brief Adds a handle snapshot to be returned by Handles().
   //!
-  //! \param[in] region The handle snapshot that will be included in Handles().
+  //! \param[in] handle The handle snapshot that will be included in Handles().
   void AddHandle(const HandleSnapshot& handle) {
     handles_.push_back(handle);
   }

snapshot/win/exception_snapshot_win.h

@@ -53,9 +53,9 @@ class ExceptionSnapshotWin final : public ExceptionSnapshot {
   //! \param[in] process_reader A ProcessReader for the process that sustained
   //!     the exception.
   //! \param[in] thread_id The thread ID in which the exception occurred.
-  //! \param[in] exception_pointers_address The address of an
+  //! \param[in] exception_pointers The address of an `EXCEPTION_POINTERS`
-  //!     `EXCEPTION_POINTERS` record in the target process, passed through from
+  //!     record in the target process, passed through from the exception
-  //!     the exception handler.
+  //!     handler.
   //!
   //! \note If the exception was triggered by
   //!     CrashpadClient::DumpAndCrashTargetProcess(), this has the side-effect

snapshot/win/pe_image_annotations_reader.h

@@ -41,8 +41,8 @@ class PEImageAnnotationsReader {
   //! \brief Constructs the object.
   //!
   //! \param[in] process_reader The reader for the remote process.
-  //! \param[in] image_reader The PEImageReader for the PE image file contained
+  //! \param[in] pe_image_reader The PEImageReader for the PE image file
-  //!     within the remote process.
+  //!     contained within the remote process.
   //! \param[in] name The module's name, a string to be used in logged messages.
   //!     This string is for diagnostic purposes only, and may be empty.
   PEImageAnnotationsReader(ProcessReaderWin* process_reader,

snapshot/win/thread_snapshot_win.h

@@ -48,7 +48,7 @@ class ThreadSnapshotWin final : public ThreadSnapshot {
   //!     the thread.
   //! \param[in] process_reader_thread The thread within the ProcessReaderWin
   //!     for which the snapshot should be created.
-  //! \param[in] gather_indirectly_referenced_memory_bytes_remaining. If
+  //! \param[in,out] gather_indirectly_referenced_memory_bytes_remaining If
   //!     non-null, add extra memory regions to the snapshot pointed to by the
   //!     thread's stack. The size of the regions added is subtracted from the
   //!     count, and when it's `0`, no more regions will be added.

test/win/win_multiprocess.h

@@ -71,7 +71,7 @@ class WinMultiprocess {
   //!
   //! The default expected termination code is `EXIT_SUCCESS` (`0`).
   //!
-  //! \param[in] code The expected exit status of the child.
+  //! \param[in] exit_code The expected exit status of the child.
   void SetExpectedChildExitCode(unsigned int exit_code);
 
   //! \brief Returns the read pipe's file handle.

tools/tool_support.h

@@ -41,6 +41,8 @@ class ToolSupport {
   //!     of its arguments.
   //!
   //! \param[in] me The tool’s name, the basename of `argv[0]`.
+  //! \param[in] hint A hint to display before the suggestion to try `--help`.
+  //!     Optional, may be `nullptr`, in which case no hint will be presented.
   static void UsageHint(const base::FilePath& me, const char* hint);
 
 #if defined(OS_POSIX) || DOXYGEN

util/mach/child_port_handshake.h

@@ -218,6 +218,9 @@ class ChildPortHandshake {
   //!  - Regardless of return value, destroys the server’s receive right and
   //!    closes the pipe.
   //!
+  //! \param[in] server_write_fd The write side of the pipe shared with the
+  //!     client process. This function takes ownership of this file descriptor,
+  //!     and will close it prior to returning.
   //! \param[in] port_right_type The port right type expected to be received
   //!     from the client. If the port right received from the client does not
   //!     match the expected type, the received port right will be destroyed,
@@ -253,9 +256,9 @@ class ChildPortHandshake {
   //! `simpleroutine`, and the server does not send a reply. This allows
   //! check-in to occur without blocking to wait for a reply.
   //!
-  //! \param[in] pipe_read The “read” side of the pipe shared with the server
+  //! \param[in] client_read_fd The “read” side of the pipe shared with the
-  //!     process. This function takes ownership of this file descriptor, and
+  //!     server process. This function takes ownership of this file descriptor,
-  //!     will close it prior to returning.
+  //!     and will close it prior to returning.
   //! \param[in] port The port right that will be passed to the server by
   //!     `child_port_check_in()`.
   //! \param[in] right_type The right type to furnish the server with. If \a

util/mach/child_port_server.h

@@ -37,6 +37,10 @@ class ChildPortServer : public MachMessageServer::Interface {
     //! This behaves equivalently to a `handle_child_port_check_in()` function
     //! used with `child_port_server()`.
     //!
+    //! \param[in] server
+    //! \param[in] token
+    //! \param[in] port
+    //! \param[in] right_type
     //! \param[in] trailer The trailer received with the request message.
     //! \param[out] destroy_request `true` if the request message is to be
     //!     destroyed even when this method returns success. See

util/mach/exc_client_variants.h

@@ -56,15 +56,25 @@ namespace crashpad {
 //! and may be set to `0` (\a old_state_count) or `nullptr` (the remaining
 //! parameters).
 //!
+//! Except as noted, the parameters and return value are equivalent to those of
+//! the `*exception_raise*()` family of functions.
+//!
 //! \param[in] behavior The exception behavior, which dictates which function
 //!     will be called. It is an error to call this function with an invalid
 //!     value for \a behavior.
-//! \param[in] code If \behavior indicates a behavior without
+//! \param[in] exception_port
+//! \param[in] thread
+//! \param[in] task
+//! \param[in] exception
+//! \param[in] code If \a behavior indicates a behavior without
 //!     `MACH_EXCEPTION_CODES`, the elements of \a code will be truncated in
 //!     order to be passed to the appropriate exception handler.
-//!
+//! \param[in] code_count
-//! All other parameters are treated equivalently to their treatment by the
+//! \param[in,out] flavor
-//! `*exception_raise*()` family of functions.
+//! \param[in] old_state
+//! \param[in] old_state_count
+//! \param[out] new_state
+//! \param[out] new_state_count
 //!
 //! \return The return value of the function called.
 kern_return_t UniversalExceptionRaise(exception_behavior_t behavior,

util/mach/exc_client_variants_test.cc

@@ -115,7 +115,7 @@ class TestExcClientVariants : public MachMultiprocess,
       }
 
       // Use a flavor known to be different from the incoming flavor, for a test
-      // of the “out” side of the inout flavor parameter.
+      // of the “out” side of the in-out flavor parameter.
       *flavor = exception_ + 20;
       *new_state_count = MACHINE_THREAD_STATE_COUNT;
 

util/mach/exc_server_variants.h

@@ -64,17 +64,32 @@ class UniversalMachExcServer final : public MachMessageServer::Interface {
     //! This behaves equivalently to a `catch_exception_raise_state_identity()`
     //! function used with `exc_server()`, or a
     //! `catch_mach_exception_raise_state_identity()` function used with
-    //! `mach_exc_server()`. The meanings of most parameters are identical to
+    //! `mach_exc_server()`. Except as noted, the parameters and return value
-    //! their meanings to these functions.
+    //! are equivalent to those of these other functions.
     //!
     //! \param[in] behavior `EXCEPTION_DEFAULT`, `EXCEPTION_STATE`,
     //!     or `EXCEPTION_STATE_IDENTITY`, possibly with `MACH_EXCEPTION_CODES`
     //!     ORed in. This identifies which exception request message was
     //!     processed and thus which other parameters are valid.
+    //! \param[in] exception_port
+    //! \param[in] thread
+    //! \param[in] task
+    //! \param[in] exception
+    //! \param[in] code
+    //! \param[in] code_count
+    //! \param[in,out] flavor
+    //! \param[in] old_state
+    //! \param[in] old_state_count
+    //! \param[out] new_state
+    //! \param[out] new_state_count
     //! \param[in] trailer The trailer received with the request message.
-    //! \param[out] destroy_request `true` if the request message is to be
+    //! \param[out] destroy_complex_request `true` if the request message is to
-    //!     destroyed even when this method returns success. See
+    //!     be destroyed even when this method returns success. See
     //!     MachMessageServer::Interface.
+    //!
+    //! \return A code indicating whether the exception was handled. See
+    //!     ExcServerSuccessfulReturnValue() for success codes. On failure,
+    //!     a code such as `KERN_FAILURE`.
     virtual kern_return_t CatchMachException(
         exception_behavior_t behavior,
         exception_handler_t exception_port,
@@ -201,7 +216,7 @@ kern_return_t ExcServerSuccessfulReturnValue(exception_type_t exception,
 //!     from the \a new_state parameter of
 //!     internal::SimplifiedExcServer::Interface::CatchException(), for example.
 //!     This parameter is untouched if \a behavior is not state-carrying.
-//! \param[inout] new_state_count On entry, the number of `natural_t` words
+//! \param[in,out] new_state_count On entry, the number of `natural_t` words
 //!     available to be written to in \a new_state. On return, the number of
 //!     significant `natural_t` words in \a new_state. This may be taken
 //!     directly from the \a new_state_count parameter of

util/mach/mach_message.h

@@ -53,7 +53,8 @@ enum : mach_msg_timeout_t {
 //! ClockMonotonicNanoseconds(), although this is an implementation detail.
 using MachMessageDeadline = uint64_t;
 
-//! \brief Special constants used as \ref MachMessageDeadline values.
+//! \brief Special constants used as \ref crashpad::MachMessageDeadline
+//!     "MachMessageDeadline" values.
 enum : MachMessageDeadline {
   //! \brief MachMessageWithDeadline() should not block at all in its operation.
   kMachMessageDeadlineNonblocking = 0,
@@ -98,15 +99,22 @@ MachMessageDeadline MachMessageDeadlineFromTimeout(
 //! Except as noted, the parameters and return value are identical to those of
 //! `mach_msg()`.
 //!
+//! \param[in,out] message
+//! \param[in] options
+//! \param[in] receive_size
+//! \param[in] receive_port
 //! \param[in] deadline The time by which this call should complete. If the
 //!     deadline is exceeded, this call will return `MACH_SEND_TIMED_OUT` or
 //!     `MACH_RCV_TIMED_OUT`.
+//! \param[in] notify_port
 //! \param[in] run_even_if_expired If `true`, a deadline that is expired when
 //!     this function is called will be treated as though a deadline of
 //!     #kMachMessageDeadlineNonblocking had been specified. When `false`, an
 //!     expired deadline will result in a `MACH_SEND_TIMED_OUT` or
 //!     `MACH_RCV_TIMED_OUT` return value, even if the deadline is already
 //!     expired when the function is called.
+//!
+//! \return The return value of `mach_msg()`
 mach_msg_return_t MachMessageWithDeadline(mach_msg_header_t* message,
                                           mach_msg_option_t options,
                                           mach_msg_size_t receive_size,
@@ -134,9 +142,9 @@ void PrepareMIGReplyFromRequest(const mach_msg_header_t* in_header,
 
 //! \brief Sets the error code in a reply message for a MIG server routine.
 //!
-//! \param[inout] out_header The reply message to operate on. \a out_header will
+//! \param[in,out] out_header The reply message to operate on. \a out_header
-//!     be treated as a `mig_reply_error_t*` and its `RetCode` field will be
+//!     will be treated as a `mig_reply_error_t*` and its `RetCode` field will
-//!     set. This argument is accepted as a `mach_msg_header_t*` instead of a
+//!     be set. This argument is accepted as a `mach_msg_header_t*` instead of a
 //!     `mig_reply_error_t*` because that is the type that callers are expected
 //!     to possess in the C API.
 //! \param[in] error The error code to store in \a out_header.

util/misc/initialization_state_dcheck.h

@@ -35,9 +35,9 @@ namespace crashpad {
 //! Initialize() methods. The chief advantage of InitializationStateDcheck over
 //! having a member variable to track state is that when the only use of the
 //! variable is to DCHECK, it wastes space (in memory and executable code) in
-//! non-DCHECK builds unless the code is also peppered with ugly #ifdefs.
+//! non-DCHECK builds unless the code is also peppered with ugly `#%ifdef`s.
 //!
-//! This implementation concentrates the ugly #ifdefs in one location.
+//! This implementation concentrates the ugly `#%ifdef`s in one location.
 //!
 //! Usage:
 //!

util/net/http_transport.h

@@ -74,9 +74,9 @@ class HTTPTransport {
   //! \brief Performs the HTTP request with the configured parameters and waits
   //!     for the execution to complete.
   //!
-  //! \param[out] response On success, this will be set to the HTTP response
+  //! \param[out] response_body On success, this will be set to the HTTP
-  //!     body. This parameter is optional and may be set to `nullptr` if the
+  //!     response body. This parameter is optional and may be set to `nullptr`
-  //!     response body is not required.
+  //!     if the response body is not required.
   //!
   //! \return Whether or not the request was successful, defined as returning
   //!     a HTTP status 200 (OK) code.

util/stdlib/map_insert.h

@@ -21,12 +21,12 @@
 namespace crashpad {
 
 //! \brief Inserts a mapping from \a key to \a value into \a map, or replaces
-//!     an existing mapping so that \a key maps to \value.
+//!     an existing mapping so that \a key maps to \a value.
 //!
-//! This behaves similarly to `std::map<>::insert_or_assign()` proposed for
+//! This behaves similarly to `std::map<>::%insert_or_assign()` proposed for
 //! C++17, except that the \a old_value parameter is added.
 //!
-//! \param[inout] map The map to operate on.
+//! \param[in,out] map The map to operate on.
 //! \param[in] key The key that should be mapped to \a value.
 //! \param[in] value The value that \a key should map to.
 //! \param[out] old_value If \a key was previously present in \a map, this will

util/string/split_string.cc

@@ -32,21 +32,22 @@ bool SplitStringFirst(const std::string& string,
   return true;
 }
 
-std::vector<std::string> SplitString(const std::string& str, char delimiter) {
+std::vector<std::string> SplitString(const std::string& string,
+                                     char delimiter) {
   std::vector<std::string> result;
-  if (str.empty())
+  if (string.empty())
     return result;
 
   size_t start = 0;
   while (start != std::string::npos) {
-    size_t end = str.find_first_of(delimiter, start);
+    size_t end = string.find_first_of(delimiter, start);
 
     std::string part;
     if (end == std::string::npos) {
-      part = str.substr(start);
+      part = string.substr(start);
       start = std::string::npos;
     } else {
-      part = str.substr(start, end - start);
+      part = string.substr(start, end - start);
       start = end + 1;
     }
 

util/string/split_string.h

@@ -30,7 +30,7 @@ namespace crashpad {
 //!     character.
 //!
 //! \return `true` if \a string was split successfully. `false` if \a string
-//!     did not contain a \delimiter character or began with a \delimiter
+//!     did not contain a \a delimiter character or began with a \a delimiter
 //!     character.
 bool SplitStringFirst(const std::string& string,
                       char delimiter,
@@ -41,8 +41,9 @@ bool SplitStringFirst(const std::string& string,
 //!
 //! \param[in] string The string to split.
 //! \param[in] delimiter The delimiter to split at.
+//!
 //! \return The individual parts of the string.
-std::vector<std::string> SplitString(const std::string& str, char delimiter);
+std::vector<std::string> SplitString(const std::string& string, char delimiter);
 
 }  // namespace crashpad
 

util/win/command_line.h

@@ -29,7 +29,7 @@ namespace crashpad {
 //! non-empty, a space will precede \a argument.
 //!
 //! \param[in] argument The argument to append to \a command_line.
-//! \param[inout] command_line The command line being constructed.
+//! \param[in,out] command_line The command line being constructed.
 void AppendCommandLineArgument(const std::wstring& argument,
                                std::wstring* command_line);