From 952f787f4aabf1e9fc9d705bf49ac4219d2931ff Mon Sep 17 00:00:00 2001 From: Mark Mentovai Date: Mon, 7 Nov 2016 09:01:20 -0500 Subject: [PATCH 1/4] =?UTF-8?q?doc:=20Standardize=20on=20=E2=80=9CmacOS?= =?UTF-8?q?=E2=80=9D=20in=20comments?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use “macOS” as the generic unversioned name of the operating system in comments. For version-specific references, use Mac OS X through 10.6, OS X from 10.7 through 10.11, and macOS for 10.12. Change-Id: I1ebee64fbf79200bc799d4a351725dd73257b54d Reviewed-on: https://chromium-review.googlesource.com/408269 Reviewed-by: Robert Sesek --- client/crashpad_client.h | 18 +++++----- compat/mac/mach-o/getsect.cc | 10 +++--- compat/non_win/dbghelp.h | 36 +++++++++---------- minidump/minidump_extensions.h | 2 +- minidump/minidump_misc_info_writer.cc | 4 +-- snapshot/cpu_context.h | 2 +- snapshot/exception_snapshot.h | 10 +++--- snapshot/mac/cpu_context_mac.h | 4 +-- snapshot/mac/exception_snapshot_mac.h | 2 +- .../mach_o_image_annotations_reader_test.cc | 8 ++--- snapshot/mac/memory_snapshot_mac.h | 2 +- snapshot/mac/process_reader_test.cc | 2 +- snapshot/mac/process_snapshot_mac.h | 10 +++--- .../crashreporterclient.proctype | 2 +- snapshot/mac/process_types_test.cc | 4 +-- snapshot/mac/system_snapshot_mac.cc | 2 +- snapshot/mac/thread_snapshot_mac.h | 2 +- snapshot/module_snapshot.h | 16 ++++----- snapshot/system_snapshot.h | 30 ++++++++-------- third_party/apple_cctools/README.crashpad | 10 +++--- util/mac/launchd.h | 6 ++-- util/mac/mac_util.cc | 5 ++- util/mac/mac_util.h | 24 ++++++------- util/mac/service_management.h | 19 +++++----- util/mac/xattr.cc | 4 +-- util/mach/exception_types.cc | 24 ++++++------- util/mach/exception_types_test.cc | 2 +- util/mach/mach_message_server.cc | 2 +- util/mach/mach_message_server_test.cc | 6 ++-- util/misc/metrics.h | 4 +-- util/net/http_transport_test.cc | 2 +- util/posix/close_multiple.h | 4 +-- util/posix/drop_privileges.cc | 12 +++---- 33 files changed, 144 insertions(+), 146 deletions(-) diff --git a/client/crashpad_client.h b/client/crashpad_client.h index 693557e0..844512f1 100644 --- a/client/crashpad_client.h +++ b/client/crashpad_client.h @@ -44,11 +44,11 @@ class CrashpadClient { //! \brief Starts a Crashpad handler process, performing any necessary //! handshake to configure it. //! - //! This method directs crashes to the Crashpad handler. On Mac OS X, this - //! is applicable to this process and all child processes. On Windows, child - //! processes must also register by using SetHandlerIPCPipe(). + //! This method directs crashes to the Crashpad handler. On macOS, this is + //! applicable to this process and all subsequent child processes. On Windows, + //! child processes must also register by using SetHandlerIPCPipe(). //! - //! On Mac OS X, this method starts a Crashpad handler and obtains a Mach send + //! On macOS, this method starts a Crashpad handler and obtains a Mach send //! right corresponding to a receive right held by the handler process. The //! handler process runs an exception server on this port. This method sets //! the task’s exception port for `EXC_CRASH`, `EXC_RESOURCE`, and `EXC_GUARD` @@ -56,8 +56,8 @@ class CrashpadClient { //! with behavior `EXCEPTION_STATE_IDENTITY | MACH_EXCEPTION_CODES` and thread //! state flavor `MACHINE_THREAD_STATE`. Exception ports are inherited, so a //! Crashpad handler started here will remain the handler for any child - //! processes created after StartHandler() is called. Child processes do not - //! need to call StartHandler() or be aware of Crashpad in any way. The + //! processes created after StartHandler() is called. These child processes do + //! not need to call StartHandler() or be aware of Crashpad in any way. The //! Crashpad handler will receive crashes from child processes that have //! inherited it as their exception handler even after the process that called //! StartHandler() exits. @@ -109,7 +109,7 @@ class CrashpadClient { //! \brief Sets the process’ crash handler to a Mach service registered with //! the bootstrap server. //! - //! This method is only defined on OS X. + //! This method is only defined on macOS. //! //! See StartHandler() for more detail on how the port and handler are //! configured. @@ -122,7 +122,7 @@ class CrashpadClient { //! \brief Sets the process’ crash handler to a Mach port. //! - //! This method is only defined on OS X. + //! This method is only defined on macOS. //! //! See StartHandler() for more detail on how the port and handler are //! configured. @@ -234,7 +234,7 @@ class CrashpadClient { //! \brief Configures the process to direct its crashes to the default handler //! for the operating system. //! - //! On OS X, this sets the task’s exception port as in SetHandlerMachPort(), + //! On macOS, this sets the task’s exception port as in SetHandlerMachPort(), //! but the exception handler used is obtained from //! SystemCrashReporterHandler(). If the system’s crash reporter handler //! cannot be determined or set, the task’s exception ports for crash-type diff --git a/compat/mac/mach-o/getsect.cc b/compat/mac/mach-o/getsect.cc index 71d3066c..6cda9ffe 100644 --- a/compat/mac/mach-o/getsect.cc +++ b/compat/mac/mach-o/getsect.cc @@ -72,11 +72,11 @@ using GetSegmentDataType = extern "C" { -// These implementations look up their functions in libmacho at run time. If -// the system libmacho provides these functions as it normally does on Mac OS X -// 10.7 and later, the system’s versions are used directly. Otherwise, the -// versions in third_party/apple_cctools are used, which are actually just -// copies of the system’s functions. +// These implementations look up their functions in libmacho at run time. If the +// system libmacho provides these functions as it normally does on OS X 10.7 and +// later, the system’s versions are used directly. Otherwise, the versions in +// third_party/apple_cctools are used, which are actually just copies of the +// system’s functions. uint8_t* getsectiondata(const MachHeader* mhp, const char* segname, diff --git a/compat/non_win/dbghelp.h b/compat/non_win/dbghelp.h index 71ef1f4c..2845f485 100644 --- a/compat/non_win/dbghelp.h +++ b/compat/non_win/dbghelp.h @@ -279,21 +279,21 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_SYSTEM_INFO { //! component. //! //! - For Windows 7 (NT 6.1) SP1, version 6.1.7601, this would be `6`. - //! - For Mac OS X 10.9.2, this would be `10`. + //! - For macOS 10.12.1, this would be `10`. uint32_t MajorVersion; //! \brief The system’s operating system version number’s second (minor) //! component. //! //! - For Windows 7 (NT 6.1) SP1, version 6.1.7601, this would be `1`. - //! - For Mac OS X 10.9.2, this would be `9`. + //! - For macOS 10.12.1, this would be `12`. uint32_t MinorVersion; //! \brief The system’s operating system version number’s third (build or //! patch) component. //! //! - For Windows 7 (NT 6.1) SP1, version 6.1.7601, this would be `7601`. - //! - For Mac OS X 10.9.2, this would be `2`. + //! - For macOS 10.12.1, this would be `1`. uint32_t BuildNumber; //! \brief The system’s operating system family. This may be a \ref @@ -311,9 +311,9 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_SYSTEM_INFO { //! - On Windows, this is the name of the installed operating system service //! pack, such as “Service Pack 1”. If no service pack is installed, this //! field references an empty string. - //! - On Mac OS X, this is the operating system build number from `sw_vers - //! -buildVersion`. For Mac OS X 10.9.2 on most hardware types, this would - //! be `13C64`. + //! - On macOS, this is the operating system build number from `sw_vers + //! -buildVersion`. For macOS 10.12.1 on most hardware types, this would + //! be `16B2657`. //! - On Linux and other Unix-like systems, this is the kernel version from //! `uname -srvm`, possibly with additional information appended. On //! Android, the `ro.build.fingerprint` system property is appended. @@ -417,7 +417,7 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_EXCEPTION { //! \brief The top-level exception code identifying the exception, in //! operating system-specific values. //! - //! For Mac OS X minidumps, this will be an \ref EXC_x "EXC_*" exception type, + //! For macOS minidumps, this will be an \ref EXC_x "EXC_*" exception type, //! such as `EXC_BAD_ACCESS`. `EXC_CRASH` will not appear here for exceptions //! processed as `EXC_CRASH` when generated from another preceding exception: //! the original exception code will appear instead. The exception type as it @@ -427,7 +427,7 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_EXCEPTION { //! exception type, such as `EXCEPTION_ACCESS_VIOLATION`. //! //! \note This field is named ExceptionCode, but what is known as the - //! “exception code” on Mac OS X/Mach is actually stored in the + //! “exception code” on macOS/Mach is actually stored in the //! #ExceptionFlags field of a minidump file. //! //! \todo Document the possible values by OS. There may be OS-specific enums @@ -437,16 +437,16 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_EXCEPTION { //! \brief Additional exception flags that further identify the exception, in //! operating system-specific values. //! - //! For Mac OS X minidumps, this will be the value of the exception code at - //! index 0 as received by a Mach exception handler, except: + //! For macOS minidumps, this will be the value of the exception code at index + //! 0 as received by a Mach exception handler, except: //! * For exception type `EXC_CRASH` generated from another preceding //! exception, the original exception code will appear here, not the code //! as received by the Mach exception handler. //! * For exception types `EXC_RESOURCE` and `EXC_GUARD`, the high 32 bits of //! the code received by the Mach exception handler will appear here. //! - //! In all cases for Mac OS X minidumps, the code as it was received by the - //! Mach exception handler will appear at index 1 of #ExceptionInformation. + //! In all cases for macOS minidumps, the code as it was received by the Mach + //! exception handler will appear at index 1 of #ExceptionInformation. //! //! For Windows minidumps, this will either be `0` if the exception is //! continuable, or `EXCEPTION_NONCONTINUABLE` to indicate a noncontinuable @@ -475,12 +475,12 @@ struct __attribute__((packed, aligned(4))) MINIDUMP_EXCEPTION { //! \brief Additional information about the exception, specific to the //! operating system and possibly the #ExceptionCode. //! - //! For Mac OS X minidumps, this will contain the exception type as received - //! by a Mach exception handler and the values of the `codes[0]` and - //! `codes[1]` (exception code and subcode) parameters supplied to the Mach - //! exception handler. Unlike #ExceptionCode and #ExceptionFlags, the values - //! received by a Mach exception handler are used directly here even for the - //! `EXC_CRASH`, `EXC_RESOURCE`, and `EXC_GUARD` exception types. + //! For macOS minidumps, this will contain the exception type as received by a + //! Mach exception handler and the values of the `codes[0]` and `codes[1]` + //! (exception code and subcode) parameters supplied to the Mach exception + //! handler. Unlike #ExceptionCode and #ExceptionFlags, the values received by + //! a Mach exception handler are used directly here even for the `EXC_CRASH`, + //! `EXC_RESOURCE`, and `EXC_GUARD` exception types. //! For Windows, these are additional arguments (if any) as provided to //! `RaiseException()`. diff --git a/minidump/minidump_extensions.h b/minidump/minidump_extensions.h index 68fa6e04..37ab8dba 100644 --- a/minidump/minidump_extensions.h +++ b/minidump/minidump_extensions.h @@ -209,7 +209,7 @@ enum MinidumpOS : uint32_t { kMinidumpOSUnix = 0x8000, - //! \brief Mac OS X, Darwin for traditional systems. + //! \brief macOS, Darwin for traditional systems. kMinidumpOSMacOSX = 0x8101, //! \brief iOS, Darwin for mobile devices. diff --git a/minidump/minidump_misc_info_writer.cc b/minidump/minidump_misc_info_writer.cc index e880aa7f..5f88c50c 100644 --- a/minidump/minidump_misc_info_writer.cc +++ b/minidump/minidump_misc_info_writer.cc @@ -68,8 +68,8 @@ std::string BuildString(const SystemSnapshot* system_snapshot) { #if defined(OS_MACOSX) // Converts the value of the MAC_OS_VERSION_MIN_REQUIRED or // MAC_OS_X_VERSION_MAX_ALLOWED macro from to a number -// identifying the minor Mac OS X version that it represents. For example, with -// an argument of MAC_OS_X_VERSION_10_6, this function will return 6. +// identifying the minor macOS version that it represents. For example, with an +// argument of MAC_OS_X_VERSION_10_6, this function will return 6. int AvailabilityVersionToMacOSXMinorVersion(int availability) { // Through MAC_OS_X_VERSION_10_9, the minor version is the tens digit. if (availability >= 1000 && availability <= 1099) { diff --git a/snapshot/cpu_context.h b/snapshot/cpu_context.h index bfef4d09..67b298e8 100644 --- a/snapshot/cpu_context.h +++ b/snapshot/cpu_context.h @@ -133,7 +133,7 @@ struct CPUContextX86_64 { uint16_t fop; // FPU opcode union { // The expression of these union members is determined by the use of - // fxsave/fxrstor or fxsave64/fxrstor64 (fxsaveq/fxrstorq). Mac OS X and + // fxsave/fxrstor or fxsave64/fxrstor64 (fxsaveq/fxrstorq). macOS and // Windows systems use the traditional fxsave/fxrstor structure. struct { // fxsave/fxrstor diff --git a/snapshot/exception_snapshot.h b/snapshot/exception_snapshot.h index eef9f47a..4454a134 100644 --- a/snapshot/exception_snapshot.h +++ b/snapshot/exception_snapshot.h @@ -50,7 +50,7 @@ class ExceptionSnapshot { //! //! This is an operating system-specific value. //! - //! For Mac OS X, this will be an \ref EXC_x "EXC_*" exception type, such as + //! For macOS, this will be an \ref EXC_x "EXC_*" exception type, such as //! `EXC_BAD_ACCESS`. `EXC_CRASH` will not appear here for exceptions //! processed as `EXC_CRASH` when generated from another preceding exception: //! the original exception code will appear instead. The exception type as it @@ -64,7 +64,7 @@ class ExceptionSnapshot { //! //! This is an operating system-specific value. //! - //! For Mac OS X, this will be the value of the exception code at index 0 as + //! For macOS, this will be the value of the exception code at index 0 as //! received by a Mach exception handler, except: //! * For `EXC_CRASH` exceptions generated from another preceding exception, //! the original exception code will appear here, not the code as received @@ -72,7 +72,7 @@ class ExceptionSnapshot { //! * For `EXC_RESOURCE` and `EXC_GUARD` exceptions, the high 32 bits of the //! exception code at index 0 will appear here. //! - //! In all cases on Mac OS X, the full exception code at index 0 as it was + //! In all cases on macOS, the full exception code at index 0 as it was //! received will appear at index 1 of Codes(). //! //! On Windows, this will either be `0` if the exception is continuable, or @@ -85,7 +85,7 @@ class ExceptionSnapshot { //! the instruction pointer that contained an offending instruction. For //! exceptions where this value cannot be determined, it will be `0`. //! - //! For Mac OS X, this will be the value of the exception code at index 1 as + //! For macOS, this will be the value of the exception code at index 1 as //! received by a Mach exception handler. virtual uint64_t ExceptionAddress() const = 0; @@ -97,7 +97,7 @@ class ExceptionSnapshot { //! they may not be present at all. In this case, an empty vector will be //! returned. //! - //! For Mac OS X, this will be a vector containing the original exception type + //! For macOS, this will be a vector containing the original exception type //! and the values of `code[0]` and `code[1]` as received by a Mach exception //! handler. //! diff --git a/snapshot/mac/cpu_context_mac.h b/snapshot/mac/cpu_context_mac.h index 1d016cf5..c96ad3c4 100644 --- a/snapshot/mac/cpu_context_mac.h +++ b/snapshot/mac/cpu_context_mac.h @@ -27,7 +27,7 @@ namespace internal { #if defined(ARCH_CPU_X86_FAMILY) || DOXYGEN //! \brief Initializes a CPUContextX86 structure from native context structures -//! on Mac OS X. +//! on macOS. //! //! \a flavor, \a state, and \a state_count may be supplied by exception //! handlers in order for the \a context parameter to be initialized by the @@ -68,7 +68,7 @@ void InitializeCPUContextX86(CPUContextX86* context, const x86_debug_state32_t* x86_debug_state32); //! \brief Initializes a CPUContextX86_64 structure from native context -//! structures on Mac OS X. +//! structures on macOS. //! //! \a flavor, \a state, and \a state_count may be supplied by exception //! handlers in order for the \a context parameter to be initialized by the diff --git a/snapshot/mac/exception_snapshot_mac.h b/snapshot/mac/exception_snapshot_mac.h index 17720728..ec91eff8 100644 --- a/snapshot/mac/exception_snapshot_mac.h +++ b/snapshot/mac/exception_snapshot_mac.h @@ -34,7 +34,7 @@ class ProcessReader; namespace internal { //! \brief An ExceptionSnapshot of an exception sustained by a running (or -//! crashed) process on a Mac OS X system. +//! crashed) process on a macOS system. class ExceptionSnapshotMac final : public ExceptionSnapshot { public: ExceptionSnapshotMac(); diff --git a/snapshot/mac/mach_o_image_annotations_reader_test.cc b/snapshot/mac/mach_o_image_annotations_reader_test.cc index d25ba438..f4f53494 100644 --- a/snapshot/mac/mach_o_image_annotations_reader_test.cc +++ b/snapshot/mac/mach_o_image_annotations_reader_test.cc @@ -199,8 +199,8 @@ class TestMachOImageAnnotationsReader final for (const std::string& annotation : all_annotations_vector) { // Look for the expectation as a leading susbtring, because the actual // string that dyld uses will have the contents of the - // DYLD_INSERT_LIBRARIES environment variable appended to it on Mac - // OS X 10.10. + // DYLD_INSERT_LIBRARIES environment variable appended to it on OS X + // 10.10. if (annotation.substr(0, expected_annotation.length()) == expected_annotation) { found = true; @@ -217,8 +217,8 @@ class TestMachOImageAnnotationsReader final bool found = false; for (const std::string& annotation : all_annotations_vector) { // Look for the expectation as a leading substring, because the actual - // string will contain the library’s pathname and, on Mac OS X 10.9 - // and later, a reason. + // string will contain the library’s pathname and, on OS X 10.9 and + // later, a reason. if (annotation.substr(0, expected_annotation_length) == kExpectedAnnotation) { found = true; diff --git a/snapshot/mac/memory_snapshot_mac.h b/snapshot/mac/memory_snapshot_mac.h index dbb02ee7..bbc39de3 100644 --- a/snapshot/mac/memory_snapshot_mac.h +++ b/snapshot/mac/memory_snapshot_mac.h @@ -27,7 +27,7 @@ namespace crashpad { namespace internal { //! \brief A MemorySnapshot of a memory region in a process on the running -//! system, when the system runs Mac OS X. +//! system, when the system runs macOS. class MemorySnapshotMac final : public MemorySnapshot { public: MemorySnapshotMac(); diff --git a/snapshot/mac/process_reader_test.cc b/snapshot/mac/process_reader_test.cc index ed717b65..e679d2ef 100644 --- a/snapshot/mac/process_reader_test.cc +++ b/snapshot/mac/process_reader_test.cc @@ -587,7 +587,7 @@ class ScopedOpenCLNoOpKernel { ASSERT_EQ(CL_SUCCESS, rv) << "clCreateContext"; // The goal of the program in |sources| is to produce a cl_kernels image - // that doesn’t strictly conform to Mach-O expectations. On Mac OS X 10.10, + // that doesn’t strictly conform to Mach-O expectations. On OS X 10.10, // cl_kernels modules show up with an __LD,__compact_unwind section, showing // up in the __TEXT segment. MachOImageSegmentReader would normally reject // modules for this problem, but a special exception is made when this diff --git a/snapshot/mac/process_snapshot_mac.h b/snapshot/mac/process_snapshot_mac.h index 6c41a662..d3e6eb45 100644 --- a/snapshot/mac/process_snapshot_mac.h +++ b/snapshot/mac/process_snapshot_mac.h @@ -46,8 +46,8 @@ namespace crashpad { -//! \brief A ProcessSnapshot of a running (or crashed) process running on a Mac -//! OS X system. +//! \brief A ProcessSnapshot of a running (or crashed) process running on a +//! macOS system. class ProcessSnapshotMac final : public ProcessSnapshot { public: ProcessSnapshotMac(); @@ -83,21 +83,21 @@ class ProcessSnapshotMac final : public ProcessSnapshot { //! \brief Sets the value to be returned by ReportID(). //! - //! On Mac OS X, the crash report ID is under the control of the snapshot + //! On macOS, the crash report ID is under the control of the snapshot //! producer, which may call this method to set the report ID. If this is not //! done, ReportID() will return an identifier consisting entirely of zeroes. void SetReportID(const UUID& report_id) { report_id_ = report_id; } //! \brief Sets the value to be returned by ClientID(). //! - //! On Mac OS X, the client ID is under the control of the snapshot producer, + //! On macOS, the client ID is under the control of the snapshot producer, //! which may call this method to set the client ID. If this is not done, //! ClientID() will return an identifier consisting entirely of zeroes. void SetClientID(const UUID& client_id) { client_id_ = client_id; } //! \brief Sets the value to be returned by AnnotationsSimpleMap(). //! - //! On Mac OS X, all process annotations are under the control of the snapshot + //! On macOS, all process annotations are under the control of the snapshot //! producer, which may call this method to establish these annotations. //! Contrast this with module annotations, which are under the control of the //! process being snapshotted. diff --git a/snapshot/mac/process_types/crashreporterclient.proctype b/snapshot/mac/process_types/crashreporterclient.proctype index b40aa358..409782c9 100644 --- a/snapshot/mac/process_types/crashreporterclient.proctype +++ b/snapshot/mac/process_types/crashreporterclient.proctype @@ -43,7 +43,7 @@ PROCESS_TYPE_STRUCT_BEGIN(crashreporter_annotations_t) PROCESS_TYPE_STRUCT_MEMBER(uint64_t, version) // unsigned long PROCESS_TYPE_STRUCT_VERSIONED(crashreporter_annotations_t, version) - // Version 4 (Mac OS X 10.7) + // Version 4 (OS X 10.7) PROCESS_TYPE_STRUCT_MEMBER(uint64_t, message) // char* PROCESS_TYPE_STRUCT_MEMBER(uint64_t, signature_string) // char* PROCESS_TYPE_STRUCT_MEMBER(uint64_t, backtrace) // char* diff --git a/snapshot/mac/process_types_test.cc b/snapshot/mac/process_types_test.cc index 1bb8d101..ce092fe1 100644 --- a/snapshot/mac/process_types_test.cc +++ b/snapshot/mac/process_types_test.cc @@ -83,8 +83,8 @@ TEST(ProcessTypes, DyldImagesSelf) { dyld_info.all_image_info_addr); EXPECT_GT(dyld_info.all_image_info_size, 1u); - // This field is only present in the Mac OS X 10.7 SDK (at build time) and - // kernel (at run time). + // This field is only present in the OS X 10.7 SDK (at build time) and kernel + // (at run time). #if MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_7 if (MacOSXMinorVersion() >= 7) { #if !defined(ARCH_CPU_64_BITS) diff --git a/snapshot/mac/system_snapshot_mac.cc b/snapshot/mac/system_snapshot_mac.cc index 185372dd..3c39088f 100644 --- a/snapshot/mac/system_snapshot_mac.cc +++ b/snapshot/mac/system_snapshot_mac.cc @@ -228,7 +228,7 @@ uint32_t SystemSnapshotMac::CPUX86Leaf7Features() const { INITIALIZATION_STATE_DCHECK_VALID(initialized_); #if defined(ARCH_CPU_X86_FAMILY) - // The machdep.cpu.leaf7_feature_bits sysctl isn’t supported prior to Mac OS X + // The machdep.cpu.leaf7_feature_bits sysctl isn’t supported prior to OS X // 10.7, so read this by calling cpuid directly. // // machdep.cpu.max_basic could be used to check whether to read the leaf, but diff --git a/snapshot/mac/thread_snapshot_mac.h b/snapshot/mac/thread_snapshot_mac.h index bbb7f77b..28334434 100644 --- a/snapshot/mac/thread_snapshot_mac.h +++ b/snapshot/mac/thread_snapshot_mac.h @@ -33,7 +33,7 @@ class ProcessReader; namespace internal { //! \brief A ThreadSnapshot of a thread in a running (or crashed) process on a -//! Mac OS X system. +//! macOS system. class ThreadSnapshotMac final : public ThreadSnapshot { public: ThreadSnapshotMac(); diff --git a/snapshot/module_snapshot.h b/snapshot/module_snapshot.h index 5989e4ba..cd3dbd39 100644 --- a/snapshot/module_snapshot.h +++ b/snapshot/module_snapshot.h @@ -82,8 +82,8 @@ class ModuleSnapshot { //! \brief The module is a dynamic loader. //! //! This is the module responsible for loading other modules. This is - //! normally `dyld` for Mac OS X and `ld.so` for Linux and other systems - //! using ELF. + //! normally `dyld` for macOS and `ld.so` for Linux and other systems using + //! ELF. kModuleTypeDynamicLoader, }; @@ -97,7 +97,7 @@ class ModuleSnapshot { //! \brief Returns the size that the module occupies in the snapshot process’ //! address space, starting at its base address. //! - //! For Mac OS X snapshots, this method only reports the size of the `__TEXT` + //! For macOS snapshots, this method only reports the size of the `__TEXT` //! segment, because segments may not be loaded contiguously. virtual uint64_t Size() const = 0; @@ -113,7 +113,7 @@ class ModuleSnapshot { //! If no file version can be determined, the \a version_* parameters are set //! to `0`. //! - //! For Mac OS X snapshots, this is taken from the module’s `LC_ID_DYLIB` load + //! For macOS snapshots, this is taken from the module’s `LC_ID_DYLIB` load //! command for shared libraries, and is `0` for other module types. virtual void FileVersion(uint16_t* version_0, uint16_t* version_1, @@ -125,8 +125,8 @@ class ModuleSnapshot { //! If no source version can be determined, the \a version_* parameters are //! set to `0`. //! - //! For Mac OS X snapshots, this is taken from the module’s - //! `LC_SOURCE_VERSION` load command. + //! For macOS snapshots, this is taken from the module’s `LC_SOURCE_VERSION` + //! load command. virtual void SourceVersion(uint16_t* version_0, uint16_t* version_1, uint16_t* version_2, @@ -164,7 +164,7 @@ class ModuleSnapshot { //! are intended for diagnostic use, including crash analysis. A module may //! contain multiple annotations, so they are returned in a vector. //! - //! For Mac OS X snapshots, these annotations are found by interpreting the + //! For macOS snapshots, these annotations are found by interpreting the //! module’s `__DATA,__crash_info` section as `crashreporter_annotations_t`. //! System libraries using the crash reporter client interface may reference //! annotations in this structure. Additional annotations messages may be @@ -183,7 +183,7 @@ class ModuleSnapshot { //! keys and values are strings. These are referred to in Chrome as “crash //! keys.” //! - //! For Mac OS X snapshots, these annotations are found by interpreting the + //! For macOS snapshots, these annotations are found by interpreting the //! `__DATA,crashpad_info` section as `CrashpadInfo`. Clients can use the //! Crashpad client interface to store annotations in this structure. Most //! annotations under the client’s direct control will be retrievable by this diff --git a/snapshot/system_snapshot.h b/snapshot/system_snapshot.h index 82f5d480..e4227dd1 100644 --- a/snapshot/system_snapshot.h +++ b/snapshot/system_snapshot.h @@ -36,7 +36,7 @@ class SystemSnapshot { //! \brief The snapshot system’s operating system is unknown. kOperatingSystemUnknown = 0, - //! \brief Mac OS X. + //! \brief macOS. kOperatingSystemMacOSX, //! \brief Windows. @@ -198,21 +198,21 @@ class SystemSnapshot { //! in \a major, \a minor, \a bugfix, and \a build. //! //! \param[out] major The snapshot system’s operating system’s first (major) - //! version number component. This would be `10` for Mac OS X 10.9.5, and + //! version number component. This would be `10` for macOS 10.12.1, and //! `6` for Windows 7 (NT 6.1) SP1 version 6.1.7601. //! \param[out] minor The snapshot system’s operating system’s second (minor) - //! version number component. This would be `9` for Mac OS X 10.9.5, and + //! version number component. This would be `12` for macOS 10.12.1, and //! `1` for Windows 7 (NT 6.1) SP1 version 6.1.7601. //! \param[out] bugfix The snapshot system’s operating system’s third (bugfix) - //! version number component. This would be `5` for Mac OS X 10.9.5, and + //! version number component. This would be `1` for macOS 10.12.1, and //! `7601` for Windows 7 (NT 6.1) SP1 version 6.1.7601. //! \param[out] build A string further identifying an operating system - //! version. For Mac OS X 10.9.5, this would be `"13F34"`. For Windows, + //! version. For macOS 10.12.1, this would be `"16B2657"`. For Windows, //! this would be `"Service Pack 1"` if that service pack was installed. - //! For Linux and other Unix-like systems, this would be the kernel - //! version from `uname -srvm`, possibly with additional information - //! appended. On Android, the `ro.build.fingerprint` system property would - //! be appended. + //! On Android, the `ro.build.fingerprint` system property would be + //! appended. For Linux and other Unix-like systems, this would be the + //! kernel version from `uname -srvm`, possibly with additional + //! information appended. virtual void OSVersion(int* major, int* minor, int* bugfix, @@ -221,17 +221,17 @@ class SystemSnapshot { //! \brief Returns the snapshot system’s full operating system version //! information in string format. //! - //! For Mac OS X, the string contains values from the operating system and - //! kernel. A Mac OS X 10.9.5 snapshot system would be identified as `"Mac OS - //! X 10.9.5 (13F34); Darwin 13.4.0 Darwin Kernel Version 13.4.0: Sun Aug 17 - //! 19:50:11 PDT 2014; root:xnu-2422.115.4~1/RELEASE_X86_64 x86_64"`. + //! For macOS, the string contains values from the operating system and + //! kernel. A macOS 10.12.1 system snapshot would be identified as `"Mac OS + //! X 10.12.1 (16B2657); Darwin 16.1.0 Darwin Kernel Version 16.1.0: Wed Oct + //! 19 20:31:56 PDT 2016; root:xnu-3789.21.4~4/RELEASE_X86_64 x86_64"`. virtual std::string OSVersionFull() const = 0; //! \brief Returns a description of the snapshot system’s hardware in string //! format. //! - //! For Mac OS X, the string contains the Mac model and board ID. A mid-2014 - //! 15" MacBook Pro would be identified as `"MacBookPro11,3 + //! For macOS, the string contains the Mac model and board ID. A mid-2014 15" + //! MacBook Pro would be identified as `"MacBookPro11,3 //! (Mac-2BD1B31983FE1663)"`. virtual std::string MachineDescription() const = 0; diff --git a/third_party/apple_cctools/README.crashpad b/third_party/apple_cctools/README.crashpad index a2aadf72..43b08618 100644 --- a/third_party/apple_cctools/README.crashpad +++ b/third_party/apple_cctools/README.crashpad @@ -13,11 +13,11 @@ like ar, as, nm, strings, and strip, and platform-specific tools like lipo and otool. It also contains support libraries such as libmacho, which contains interfaces for dealing with Mach-O images. -libmacho is available on Mac OS X as a runtime library that is part of -libSystem, but versions of libmacho included in operating system versions prior -to Mac OS X 10.7 did not include the getsectiondata() and getsegmentdata() -functions. This library is present here to provide implementations of these -functions for systems that do not have them. +libmacho is available on macOS as a runtime library that is part of libSystem, +but versions of libmacho included in operating system versions prior to Mac OS X +10.7 did not include the getsectiondata() and getsegmentdata() functions. This +library is present here to provide implementations of these functions for +systems that do not have them. Crashpad code is not expected to use this library directly. It should use the getsectiondata() and getsegmentdata() wrappers in compat, which will use diff --git a/util/mac/launchd.h b/util/mac/launchd.h index 25450752..21b43f8d 100644 --- a/util/mac/launchd.h +++ b/util/mac/launchd.h @@ -27,9 +27,9 @@ namespace crashpad { //! \{ //! \brief Wraps the `` function of the same name. //! -//! The Mac OS X 10.10 SDK deprecates ``, although the functionality -//! it provides is still useful. These wrappers allow the deprecated functions -//! to be called without triggering deprecated-declaration warnings. +//! The OS X 10.10 SDK deprecates ``, although the functionality it +//! provides is still useful. These wrappers allow the deprecated functions to +//! be called without triggering deprecated-declaration warnings. inline launch_data_t LaunchDataAlloc(launch_data_type_t type) { return launch_data_alloc(type); diff --git a/util/mac/mac_util.cc b/util/mac/mac_util.cc index a792e511..7c51cc2e 100644 --- a/util/mac/mac_util.cc +++ b/util/mac/mac_util.cc @@ -181,9 +181,8 @@ std::string IORegistryEntryDataPropertyAsString(io_registry_entry_t entry, namespace crashpad { int MacOSXMinorVersion() { - // The Darwin major version is always 4 greater than the Mac OS X minor - // version for Darwin versions beginning with 6, corresponding to Mac OS X - // 10.2. + // The Darwin major version is always 4 greater than the macOS minor version + // for Darwin versions beginning with 6, corresponding to Mac OS X 10.2. static int mac_os_x_minor_version = DarwinMajorVersion() - 4; DCHECK(mac_os_x_minor_version >= 2); return mac_os_x_minor_version; diff --git a/util/mac/mac_util.h b/util/mac/mac_util.h index 9cedfdfb..d8b71598 100644 --- a/util/mac/mac_util.h +++ b/util/mac/mac_util.h @@ -21,8 +21,8 @@ namespace crashpad { //! \brief Returns the version of the running operating system. //! -//! \return The minor version of the operating system, such as `9` for Mac OS X -//! 10.9.2. +//! \return The minor version of the operating system, such as `12` for macOS +//! 10.12.1. //! //! \note This is similar to the base::mac::IsOS*() family of functions, but //! is provided for situations where the caller needs to obtain version @@ -35,17 +35,17 @@ int MacOSXMinorVersion(); //! All parameters are required. No parameter may be `nullptr`. //! //! \param[out] major The major version of the operating system, such as `10` -//! for Mac OS X 10.9.2. -//! \param[out] minor The major version of the operating system, such as `9` for -//! Mac OS X 10.9.2. -//! \param[out] bugfix The bugfix version of the operating system, such as `2` -//! for Mac OS X 10.9.2. -//! \param[out] build The operating system’s build string, such as "13C64" for -//! Mac OS X 10.9.2. -//! \param[out] server `true` for a Mac OS X Server installation, `false` -//! otherwise (for a desktop/laptop, client, or workstation system). +//! for macOS 10.12.1. +//! \param[out] minor The major version of the operating system, such as `12` +//! for macOS 10.12.1. +//! \param[out] bugfix The bugfix version of the operating system, such as `1` +//! for macOS 10.12.1. +//! \param[out] build The operating system’s build string, such as `"16B2657"` +//! for macOS 10.12.1. +//! \param[out] server `true` for a macOS Server installation, `false` otherwise +//! (for a desktop/laptop, client, or workstation system). //! \param[out] version_string A string representing the full operating system -//! version, such as `"Mac OS X 10.9.2 (13C64)"`. +//! version, such as `"macOS 10.12.1 (16B2657)"`. //! //! \return `true` on success, `false` on failure, with an error message logged. //! A failure is considered to have occurred if any element could not be diff --git a/util/mac/service_management.h b/util/mac/service_management.h index 802e5449..16cb45aa 100644 --- a/util/mac/service_management.h +++ b/util/mac/service_management.h @@ -28,8 +28,8 @@ namespace crashpad { //! //! \return `true` if the job was submitted successfully, otherwise `false`. //! -//! \note This function is provided because `SMJobSubmit()` is deprecated in Mac -//! OS X 10.10. It may or may not be implemented using `SMJobSubmit()` from +//! \note This function is provided because `SMJobSubmit()` is deprecated in OS +//! X 10.10. It may or may not be implemented using `SMJobSubmit()` from //! `ServiceManagement.framework`. bool ServiceManagementSubmitJob(CFDictionaryRef job_cf); @@ -42,12 +42,11 @@ bool ServiceManagementSubmitJob(CFDictionaryRef job_cf); //! \return `true` if the job was removed successfully or if an asynchronous //! attempt to remove the job was started successfully, otherwise `false`. //! -//! \note This function is provided because `SMJobRemove()` is deprecated in Mac -//! OS X 10.10. On Mac OS X 10.10, observed in DP8 14A361c, it also blocks -//! for far too long (`_block_until_job_exits()` contains a one-second -//! `sleep()`, filed as radar 18398683) and does not signal failure via its -//! return value when asked to remove a nonexistent job (filed as radar -//! 18268941). +//! \note This function is provided because `SMJobRemove()` is deprecated in OS +//! X 10.10. On OS X 10.10, observed in DP8 14A361c, it also blocks for far +//! too long (`_block_until_job_exits()` contains a one-second `sleep()`, +//! filed as radar 18398683) and does not signal failure via its return +//! value when asked to remove a nonexistent job (filed as radar 18268941). bool ServiceManagementRemoveJob(const std::string& label, bool wait); //! \brief Determines whether a specified job is loaded in the user launchd @@ -60,7 +59,7 @@ bool ServiceManagementRemoveJob(const std::string& label, bool wait); //! \note A loaded job is not necessarily presently running, nor has it //! necessarily ever run in the past. //! \note This function is provided because `SMJobCopyDictionary()` is -//! deprecated in Mac OS X 10.10. It may or may not be implemented using +//! deprecated in OS X 10.10. It may or may not be implemented using //! `SMJobCopyDictionary()` from `ServiceManagement.framework`. bool ServiceManagementIsJobLoaded(const std::string& label); @@ -72,7 +71,7 @@ bool ServiceManagementIsJobLoaded(const std::string& label); //! \return The job’s process ID if running, otherwise `0`. //! //! \note This function is provided because `SMJobCopyDictionary()` is -//! deprecated in Mac OS X 10.10. It may or may not be implemented using +//! deprecated in OS X 10.10. It may or may not be implemented using //! `SMJobCopyDictionary()` from `ServiceManagement.framework`. pid_t ServiceManagementIsJobRunning(const std::string& label); diff --git a/util/mac/xattr.cc b/util/mac/xattr.cc index 138de3e4..75d7938d 100644 --- a/util/mac/xattr.cc +++ b/util/mac/xattr.cc @@ -117,8 +117,8 @@ bool WriteXattrInt(const base::FilePath& file, XattrStatus ReadXattrTimeT(const base::FilePath& file, const base::StringPiece& name, time_t* value) { - // time_t on OS X is defined as a long, but it will be read into an - // int64_t here, since there is no string conversion method for long. + // time_t on macOS is defined as a long, but it will be read into an int64_t + // here, since there is no string conversion method for long. std::string tmp; XattrStatus status; if ((status = ReadXattr(file, name, &tmp)) != XattrStatus::kOK) diff --git a/util/mach/exception_types.cc b/util/mach/exception_types.cc index cef90f9a..09366b57 100644 --- a/util/mach/exception_types.cc +++ b/util/mach/exception_types.cc @@ -29,9 +29,9 @@ extern "C" { -// proc_get_wakemon_params() is present in the Mac OS X 10.9 SDK, but no -// declaration is provided. This provides a declaration and marks it for weak -// import if the deployment target is below 10.9. +// proc_get_wakemon_params() is present in the OS X 10.9 SDK, but no declaration +// is provided. This provides a declaration and marks it for weak import if the +// deployment target is below 10.9. int proc_get_wakemon_params(pid_t pid, int* rate_hz, int* flags) __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); @@ -76,8 +76,8 @@ ProcGetWakemonParamsType GetProcGetWakemonParams() { namespace { // Wraps proc_get_wakemon_params(), calling it if the system provides it. It’s -// present on Mac OS X 10.9 and later. If it’s not available, sets errno to -// ENOSYS and returns -1. +// present on OS X 10.9 and later. If it’s not available, sets errno to ENOSYS +// and returns -1. int ProcGetWakemonParams(pid_t pid, int* rate_hz, int* flags) { #if MAC_OS_X_VERSION_MAX_ALLOWED < MAC_OS_X_VERSION_10_9 // proc_get_wakemon_params() isn’t in the SDK. Look it up dynamically. @@ -146,17 +146,17 @@ bool IsExceptionNonfatalResource(exception_type_t exception, // RLIMIT_CPU_USAGE_MONITOR as the second argument and CPUMON_MAKE_FATAL set // in the flags. if (MacOSXMinorVersion() >= 10) { - // In Mac OS X 10.10, the exception code indicates whether the exception - // is fatal. See 10.10 xnu-2782.1.97/osfmk/kern/thread.c + // In OS X 10.10, the exception code indicates whether the exception is + // fatal. See 10.10 xnu-2782.1.97/osfmk/kern/thread.c // THIS_THREAD_IS_CONSUMING_TOO_MUCH_CPU__SENDING_EXC_RESOURCE(). return resource_flavor == FLAVOR_CPU_MONITOR; } - // In Mac OS X 10.9, there’s no way to determine whether the exception is - // fatal. Unlike RESOURCE_TYPE_WAKEUPS below, there’s no way to determine - // this outside the kernel. proc_rlimit_control()’s RLIMIT_CPU_USAGE_MONITOR - // is the only interface to modify CPUMON_MAKE_FATAL, but it’s only able to - // set this bit, not obtain its current value. + // In OS X 10.9, there’s no way to determine whether the exception is fatal. + // Unlike RESOURCE_TYPE_WAKEUPS below, there’s no way to determine this + // outside the kernel. proc_rlimit_control()’s RLIMIT_CPU_USAGE_MONITOR is + // the only interface to modify CPUMON_MAKE_FATAL, but it’s only able to set + // this bit, not obtain its current value. // // Default to assuming that these exceptions are nonfatal. They are nonfatal // by default and no users of proc_rlimit_control() were found on 10.9.5 diff --git a/util/mach/exception_types_test.cc b/util/mach/exception_types_test.cc index 372b57f0..d82dcbb9 100644 --- a/util/mach/exception_types_test.cc +++ b/util/mach/exception_types_test.cc @@ -102,7 +102,7 @@ TEST(ExceptionTypes, IsExceptionNonfatalResource) { EXPECT_TRUE(IsExceptionNonfatalResource(EXC_RESOURCE, code, pid)); if (MacOSXMinorVersion() >= 10) { - // FLAVOR_CPU_MONITOR_FATAL was introduced in Mac OS X 10.10. + // FLAVOR_CPU_MONITOR_FATAL was introduced in OS X 10.10. code = 0; EXC_RESOURCE_ENCODE_TYPE(code, RESOURCE_TYPE_CPU); EXC_RESOURCE_ENCODE_FLAVOR(code, FLAVOR_CPU_MONITOR_FATAL); diff --git a/util/mach/mach_message_server.cc b/util/mach/mach_message_server.cc index 0af19018..39633730 100644 --- a/util/mach/mach_message_server.cc +++ b/util/mach/mach_message_server.cc @@ -147,7 +147,7 @@ mach_msg_return_t MachMessageServer::Run(Interface* interface, // mach_msg_server() and mach_msg_server_once() would consider whether // |options| contains MACH_SEND_TRAILER and include MAX_TRAILER_SIZE in this - // computation if it does, but that option is ineffective on OS X. + // computation if it does, but that option is ineffective on macOS. const mach_msg_size_t reply_size = interface->MachMessageServerReplySize(); DCHECK_GE(reply_size, sizeof(mach_msg_empty_send_t)); const mach_msg_size_t reply_alloc = round_page(reply_size); diff --git a/util/mach/mach_message_server_test.cc b/util/mach/mach_message_server_test.cc index fc45e262..a2d2eb1f 100644 --- a/util/mach/mach_message_server_test.cc +++ b/util/mach/mach_message_server_test.cc @@ -321,9 +321,9 @@ class TestMachMessageServer : public MachMessageServer::Interface, kern_return_t kr; if (options_.child_send_all_requests_before_receiving_any_replies) { - // On Mac OS X 10.10, the queue limit of a new Mach port seems to be 2 - // by default, which is below the value of MACH_PORT_QLIMIT_DEFAULT. Set - // the port’s queue limit explicitly here. + // On OS X 10.10, the queue limit of a new Mach port seems to be 2 by + // default, which is below the value of MACH_PORT_QLIMIT_DEFAULT. Set the + // port’s queue limit explicitly here. mach_port_limits limits = {}; limits.mpl_qlimit = MACH_PORT_QLIMIT_DEFAULT; kr = mach_port_set_attributes(mach_task_self(), diff --git a/util/misc/metrics.h b/util/misc/metrics.h index a6a7f986..fd2e1200 100644 --- a/util/misc/metrics.h +++ b/util/misc/metrics.h @@ -89,12 +89,12 @@ class Metrics { //! \brief Unexpected exception behavior. //! - //! This value is only used on Mac OS X. + //! This value is only used on macOS. kUnexpectedExceptionBehavior = 1, //! \brief Failed due to attempt to suspend self. //! - //! This value is only used on Mac OS X. + //! This value is only used on macOS. kFailedDueToSuspendSelf = 2, //! \brief The process snapshot could not be captured. diff --git a/util/net/http_transport_test.cc b/util/net/http_transport_test.cc index bbfe8780..e8495308 100644 --- a/util/net/http_transport_test.cc +++ b/util/net/http_transport_test.cc @@ -279,7 +279,7 @@ TEST(HTTPTransport, UnchunkedPlainText) { } void RunUpload33k(bool has_content_length) { - // On OS X, NSMutableURLRequest winds up calling into a CFReadStream’s Read() + // On macOS, NSMutableURLRequest winds up calling into a CFReadStream’s Read() // callback with a 32kB buffer. Make sure that it’s able to get everything // when enough is available to fill this buffer, requiring more than one // Read(). diff --git a/util/posix/close_multiple.h b/util/posix/close_multiple.h index 2a66f28a..baf72b2b 100644 --- a/util/posix/close_multiple.h +++ b/util/posix/close_multiple.h @@ -28,8 +28,8 @@ namespace crashpad { //! //! Unlike the BSD function, this function may not close file descriptors //! immediately, but may instead mark them as close-on-exec. The actual behavior -//! chosen is specific to the operating system. On Mac OS X, file descriptors -//! are marked close-on-exec instead of being closed outright in order to avoid +//! chosen is specific to the operating system. On macOS, file descriptors are +//! marked close-on-exec instead of being closed outright in order to avoid //! raising `EXC_GUARD` exceptions for guarded file descriptors that are //! protected against `close()`. //! diff --git a/util/posix/drop_privileges.cc b/util/posix/drop_privileges.cc index 5c809904..884a411c 100644 --- a/util/posix/drop_privileges.cc +++ b/util/posix/drop_privileges.cc @@ -31,10 +31,10 @@ void DropPrivileges() { // is set not equal to the real ID. This code never specifies -1, so the // setreuid() and setregid() alone should work according to the standard. // - // In practice, on Mac OS X, setuid() and setgid() (or seteuid() and - // setegid()) must be called first. Otherwise, setreuid() and setregid() do - // not alter the saved IDs, leaving open the possibility for future privilege - // escalation. + // In practice, on older versions of macOS, setuid() and setgid() (or + // seteuid() and setegid()) must be called first. Otherwise, setreuid() and + // setregid() do not alter the saved IDs, leaving open the possibility for + // future privilege escalation. // // The problem exists in 10.9.5 xnu-2422.115.4/bsd/kern/kern_prot.c // setreuid(). Based on its comments, it purports to set the svuid to the new @@ -45,8 +45,8 @@ void DropPrivileges() { // is different from the desired euid. The workaround of calling setuid() or // seteuid() before setreuid() works because it sets the euid so that by the // time setreuid() runs, the old euid is actually the value that ought to be - // set as the svuid. setregid() is similar. This bug is filed as radar - // 18987552. + // set as the svuid. setregid() is similar. This bug was reported as radar + // 18987552, fixed in 10.10.3 and security updates to 10.9.5 and 10.8.5. // // setuid() and setgid() alone will only set the saved IDs when running as // root. When running a setuid non-root or setgid program, they do not alter From acabe35928f5c6b27e4b0ea272e3d25c0a3e3070 Mon Sep 17 00:00:00 2001 From: Mark Mentovai Date: Tue, 8 Nov 2016 14:23:09 -0500 Subject: [PATCH 2/4] 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); From ac2e7cfbb2dad22ec69e92c0344abffcee0cdf20 Mon Sep 17 00:00:00 2001 From: Mark Mentovai Date: Tue, 8 Nov 2016 14:24:54 -0500 Subject: [PATCH 3/4] doc: Make Doxygen-generated HTML interface documentation prettier MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This provides custom CSS to override Doxygen’s default font choices. It uses the Open Sans and Source Code Pro as used on Gitiles and PolyGerrit. A slightly-improved Doxygen main page is included as well. Change-Id: Ib9f7e7d3eef7d3b78231e2dc9430aa8758590773 Reviewed-on: https://chromium-review.googlesource.com/408715 Reviewed-by: Robert Sesek --- doc/support/crashpad.doxy | 2 +- doc/support/crashpad.doxy.h | 10 ++++++ doc/support/crashpad_doxygen.css | 60 ++++++++++++++++++++++++++++++++ 3 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 doc/support/crashpad_doxygen.css diff --git a/doc/support/crashpad.doxy b/doc/support/crashpad.doxy index dd2d4031..198b7176 100644 --- a/doc/support/crashpad.doxy +++ b/doc/support/crashpad.doxy @@ -1129,7 +1129,7 @@ HTML_STYLESHEET = # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_EXTRA_STYLESHEET = +HTML_EXTRA_STYLESHEET = doc/support/crashpad_doxygen.css # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the HTML output directory. Note diff --git a/doc/support/crashpad.doxy.h b/doc/support/crashpad.doxy.h index 5bfefedd..ae328d30 100644 --- a/doc/support/crashpad.doxy.h +++ b/doc/support/crashpad.doxy.h @@ -22,3 +22,13 @@ //! \namespace crashpad::test //! \brief The testing namespace, for use in test code only. + +//! \mainpage Crashpad Interface Documentation +//! +//! Most generated interface documentation is reachable through Namespaces, Classes +//! (includes `struct`s, `union`s, and interfaces), or Files (includes macros). +//! +//! Additional documentation is available at the Crashpad home page. diff --git a/doc/support/crashpad_doxygen.css b/doc/support/crashpad_doxygen.css new file mode 100644 index 00000000..f21cfe90 --- /dev/null +++ b/doc/support/crashpad_doxygen.css @@ -0,0 +1,60 @@ +/* Copyright 2016 The Crashpad Authors. All rights reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. */ + +@import "https://fonts.googleapis.com/css?family=Open+Sans:300,400,700&subset=latin,cyrillic-ext,greek-ext,cyrillic,greek,vietnamese,latin-ext"; +@import "https://fonts.googleapis.com/css?family=Source+Code+Pro"; + +body, +table, +div, +p, +dl, +.title, +.icon, +table.directory, +.navpath li.navelem a, +#projectname, +#projectbrief, +#projectnumber, +div.toc li, +div.toc h3, +#powerTip div, +.sm-dox a, +.sm-dox a:focus, +.sm-dox a:hover, +.sm-dox a:active { + font-family: 'Open Sans', + 'Lucida Grande', + 'Lucida Sans Unicode', + Helvetica, + Arial, + sans-serif; +} + +code, +tt, +pre.fragment, +div.line, +.overload, +.params .paramdir, +.sm-dox a span.sub-arrow { + font-family: 'Source Code Pro', + Monaco, + 'Lucida Console', + monospace; +} + +.icon { + height: auto; +} From f191fff64dd3e5de8abcbf4671aefe725f91e07d Mon Sep 17 00:00:00 2001 From: Mark Mentovai Date: Tue, 8 Nov 2016 14:25:57 -0500 Subject: [PATCH 4/4] =?UTF-8?q?doc:=20Fix=20bad=20merge=20resulting=20in?= =?UTF-8?q?=20twin=20=E2=80=9CMan=20Pages=E2=80=9D=20links=20in=20nav=20ba?= =?UTF-8?q?r?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit BUG=crashpad:138 Change-Id: I84ba67b7010c6686c228801f91995d436676ef3c Reviewed-on: https://chromium-review.googlesource.com/408562 Reviewed-by: Robert Sesek --- navbar.md | 1 - 1 file changed, 1 deletion(-) diff --git a/navbar.md b/navbar.md index 8eb7e1c4..d530414f 100644 --- a/navbar.md +++ b/navbar.md @@ -19,7 +19,6 @@ limitations under the License. * [Home][home] * [Developing](/doc/developing.md) * [Interface Docs](https://crashpad.chromium.org/doxygen/) - * [Man Pages](https://crashpad.chromium.org/man/) * [Man Pages](/doc/man.md) * [Source Code](https://chromium.googlesource.com/crashpad/crashpad/)