From acabe35928f5c6b27e4b0ea272e3d25c0a3e3070 Mon Sep 17 00:00:00 2001 From: Mark Mentovai Date: Tue, 8 Nov 2016 14:23:09 -0500 Subject: [PATCH] doc: Fix all Doxygen warnings, cleaning up some generated documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- client/crashpad_info.h | 6 ++--- client/prune_crash_reports.h | 2 +- compat/non_win/dbghelp.h | 14 ++++++----- doc/appengine/README | 2 +- doc/support/crashpad.doxy | 11 +++++--- doc/support/generate.sh | 5 ---- minidump/minidump_extensions.h | 4 +-- .../minidump_module_crashpad_info_writer.h | 11 ++++---- snapshot/capture_memory.h | 8 +++--- snapshot/exception_snapshot.h | 4 +-- snapshot/mac/exception_snapshot_mac.h | 8 ++++++ snapshot/mac/process_reader.h | 6 ++--- snapshot/mac/process_types/custom.cc | 4 +++ snapshot/system_snapshot.h | 4 +-- snapshot/test/test_process_snapshot.h | 2 +- snapshot/win/exception_snapshot_win.h | 6 ++--- snapshot/win/pe_image_annotations_reader.h | 4 +-- snapshot/win/thread_snapshot_win.h | 2 +- test/win/win_multiprocess.h | 2 +- tools/tool_support.h | 2 ++ util/mach/child_port_handshake.h | 9 ++++--- util/mach/child_port_server.h | 4 +++ util/mach/exc_client_variants.h | 18 ++++++++++--- util/mach/exc_client_variants_test.cc | 2 +- util/mach/exc_server_variants.h | 25 +++++++++++++++---- util/mach/mach_message.h | 16 +++++++++--- util/misc/initialization_state_dcheck.h | 4 +-- util/net/http_transport.h | 6 ++--- util/stdlib/map_insert.h | 6 ++--- util/string/split_string.cc | 11 ++++---- util/string/split_string.h | 5 ++-- util/win/command_line.h | 2 +- 32 files changed, 136 insertions(+), 79 deletions(-) diff --git a/client/crashpad_info.h b/client/crashpad_info.h index 9e7abfc1..0462eaf9 100644 --- a/client/crashpad_info.h +++ b/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 - //! by \a data and \a size is owned by the caller and must remain valid while - //! it is in effect for the CrashpadInfo object. + //! minidump as separate stream with type \a stream_type. The memory referred + //! to by \a data and \a size is owned by the caller and must remain valid + //! 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. diff --git a/client/prune_crash_reports.h b/client/prune_crash_reports.h index b66e9349..6dac5f30 100644 --- a/client/prune_crash_reports.h +++ b/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 { diff --git a/compat/non_win/dbghelp.h b/compat/non_win/dbghelp.h index 2845f485..78ec2952 100644 --- a/compat/non_win/dbghelp.h +++ b/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_*" - //! exception type, such as `EXCEPTION_ACCESS_VIOLATION`. + //! For Windows minidumps, this will be an `EXCEPTION_*` exception type, such + //! 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_GUARD or \ref PAGE_x PAGE_NOCACHE, as needed. + //! \ref PAGE_x "PAGE_EXECUTE", \ref PAGE_x "PAGE_NOACCESS", etc.), along + //! 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; diff --git a/doc/appengine/README b/doc/appengine/README index b92e311b..9434ba09 100644 --- a/doc/appengine/README +++ b/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. diff --git a/doc/support/crashpad.doxy b/doc/support/crashpad.doxy index 0d216454..dd2d4031 100644 --- a/doc/support/crashpad.doxy +++ b/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 diff --git a/doc/support/generate.sh b/doc/support/generate.sh index aa3d7035..1e5bc92f 100755 --- a/doc/support/generate.sh +++ b/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}/" diff --git a/minidump/minidump_extensions.h b/minidump/minidump_extensions.h index 37ab8dba..00ac6e88 100644 --- a/minidump/minidump_extensions.h +++ b/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; diff --git a/minidump/minidump_module_crashpad_info_writer.h b/minidump/minidump_module_crashpad_info_writer.h index ab77447b..d79ac2f4 100644 --- a/minidump/minidump_module_crashpad_info_writer.h +++ b/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. - //! This object takes ownership of \a module and becomes its parent in the - //! overall tree of internal::MinidumpWritable objects. - //! \param[in] module_list_index The index of the MINIDUMP_MODULE in the - //! minidump file’s MINIDUMP_MODULE_LIST stream that corresponds to \a + //! \param[in] module_crashpad_info Extended Crashpad-specific information + //! about the module. This object takes ownership of \a + //! module_crashpad_info and becomes its parent in the overall tree of + //! internal::MinidumpWritable objects. + //! \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. diff --git a/snapshot/capture_memory.h b/snapshot/capture_memory.h index ef5f4ed9..d6a3a6df 100644 --- a/snapshot/capture_memory.h +++ b/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 - //! target process, and that handles adding new ranges. + //! \param[in] delegate A Delegate that handles reading from the target + //! 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 - //! target process, and that handles adding new ranges. + //! \param[in] delegate A Delegate that handles reading from the target + //! process and adding new ranges. static void PointedToByMemoryRange(const MemorySnapshot& memory, Delegate* delegate); diff --git a/snapshot/exception_snapshot.h b/snapshot/exception_snapshot.h index 4454a134..11a94153 100644 --- a/snapshot/exception_snapshot.h +++ b/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 - //! such as `EXCEPTION_ACCESS_VIOLATION`. + //! For Windows, this will be an `EXCEPTION_*` exception type, such as + //! `EXCEPTION_ACCESS_VIOLATION`. virtual uint32_t Exception() const = 0; //! \brief Returns the second-level exception code identifying the exception. diff --git a/snapshot/mac/exception_snapshot_mac.h b/snapshot/mac/exception_snapshot_mac.h index ec91eff8..9a6ddcaa 100644 --- a/snapshot/mac/exception_snapshot_mac.h +++ b/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. diff --git a/snapshot/mac/process_reader.h b/snapshot/mac/process_reader.h index 57d02641..c3696110 100644 --- a/snapshot/mac/process_reader.h +++ b/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. diff --git a/snapshot/mac/process_types/custom.cc b/snapshot/mac/process_types/custom.cc index 60c6e504..5fe92288 100644 --- a/snapshot/mac/process_types/custom.cc +++ b/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::ReadInto( } // namespace internal } // namespace process_types } // namespace crashpad + +#endif // !DOXYGEN diff --git a/snapshot/system_snapshot.h b/snapshot/system_snapshot.h index e4227dd1..549f0b67 100644 --- a/snapshot/system_snapshot.h +++ b/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, diff --git a/snapshot/test/test_process_snapshot.h b/snapshot/test/test_process_snapshot.h index 633d9b9b..7dd31247 100644 --- a/snapshot/test/test_process_snapshot.h +++ b/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); } diff --git a/snapshot/win/exception_snapshot_win.h b/snapshot/win/exception_snapshot_win.h index 3ccf38ae..7aedb3a4 100644 --- a/snapshot/win/exception_snapshot_win.h +++ b/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 - //! `EXCEPTION_POINTERS` record in the target process, passed through from - //! the exception handler. + //! \param[in] exception_pointers The address of an `EXCEPTION_POINTERS` + //! record in the target process, passed through from the exception + //! handler. //! //! \note If the exception was triggered by //! CrashpadClient::DumpAndCrashTargetProcess(), this has the side-effect diff --git a/snapshot/win/pe_image_annotations_reader.h b/snapshot/win/pe_image_annotations_reader.h index 868b076c..85f3bed3 100644 --- a/snapshot/win/pe_image_annotations_reader.h +++ b/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 - //! within the remote process. + //! \param[in] pe_image_reader The PEImageReader for the PE image file + //! 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, diff --git a/snapshot/win/thread_snapshot_win.h b/snapshot/win/thread_snapshot_win.h index 7b566885..7df23ab3 100644 --- a/snapshot/win/thread_snapshot_win.h +++ b/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. diff --git a/test/win/win_multiprocess.h b/test/win/win_multiprocess.h index 418df790..663c7594 100644 --- a/test/win/win_multiprocess.h +++ b/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. diff --git a/tools/tool_support.h b/tools/tool_support.h index 79dc7524..e3a50614 100644 --- a/tools/tool_support.h +++ b/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 diff --git a/util/mach/child_port_handshake.h b/util/mach/child_port_handshake.h index 50de118a..429164a9 100644 --- a/util/mach/child_port_handshake.h +++ b/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 - //! process. This function takes ownership of this file descriptor, and - //! will close it prior to returning. + //! \param[in] client_read_fd The “read” side of the pipe shared with the + //! server process. This function takes ownership of this file descriptor, + //! 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 diff --git a/util/mach/child_port_server.h b/util/mach/child_port_server.h index b82e99a3..47d72e4d 100644 --- a/util/mach/child_port_server.h +++ b/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 diff --git a/util/mach/exc_client_variants.h b/util/mach/exc_client_variants.h index d96e689e..3fa06a0b 100644 --- a/util/mach/exc_client_variants.h +++ b/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. -//! -//! All other parameters are treated equivalently to their treatment by the -//! `*exception_raise*()` family of functions. +//! \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 //! //! \return The return value of the function called. kern_return_t UniversalExceptionRaise(exception_behavior_t behavior, diff --git a/util/mach/exc_client_variants_test.cc b/util/mach/exc_client_variants_test.cc index ca3101cd..29a272b9 100644 --- a/util/mach/exc_client_variants_test.cc +++ b/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; diff --git a/util/mach/exc_server_variants.h b/util/mach/exc_server_variants.h index 0d947432..c7b35d41 100644 --- a/util/mach/exc_server_variants.h +++ b/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 - //! their meanings to these functions. + //! `mach_exc_server()`. Except as noted, the parameters and return value + //! 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 - //! destroyed even when this method returns success. See + //! \param[out] destroy_complex_request `true` if the request message is to + //! 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 diff --git a/util/mach/mach_message.h b/util/mach/mach_message.h index 2fd81511..df4b6b4f 100644 --- a/util/mach/mach_message.h +++ b/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 -//! be treated as a `mig_reply_error_t*` and its `RetCode` field will be -//! set. This argument is accepted as a `mach_msg_header_t*` instead of a +//! \param[in,out] out_header The reply message to operate on. \a out_header +//! will be treated as a `mig_reply_error_t*` and its `RetCode` field will +//! 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. diff --git a/util/misc/initialization_state_dcheck.h b/util/misc/initialization_state_dcheck.h index e45a6f82..7b6df986 100644 --- a/util/misc/initialization_state_dcheck.h +++ b/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: //! diff --git a/util/net/http_transport.h b/util/net/http_transport.h index cd31facf..f9948aa2 100644 --- a/util/net/http_transport.h +++ b/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 - //! body. This parameter is optional and may be set to `nullptr` if the - //! response body is not required. + //! \param[out] response_body On success, this will be set to the HTTP + //! response body. This parameter is optional and may be set to `nullptr` + //! if the response body is not required. //! //! \return Whether or not the request was successful, defined as returning //! a HTTP status 200 (OK) code. diff --git a/util/stdlib/map_insert.h b/util/stdlib/map_insert.h index 956271b3..d2c3b842 100644 --- a/util/stdlib/map_insert.h +++ b/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 diff --git a/util/string/split_string.cc b/util/string/split_string.cc index 9d0d675a..fe7a7eb4 100644 --- a/util/string/split_string.cc +++ b/util/string/split_string.cc @@ -32,21 +32,22 @@ bool SplitStringFirst(const std::string& string, return true; } -std::vector SplitString(const std::string& str, char delimiter) { +std::vector SplitString(const std::string& string, + char delimiter) { std::vector 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; } diff --git a/util/string/split_string.h b/util/string/split_string.h index 4ea89d24..af4f953c 100644 --- a/util/string/split_string.h +++ b/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 SplitString(const std::string& str, char delimiter); +std::vector SplitString(const std::string& string, char delimiter); } // namespace crashpad diff --git a/util/win/command_line.h b/util/win/command_line.h index eb3f7124..c12d6539 100644 --- a/util/win/command_line.h +++ b/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);