doc: Update to Doxygen 1.13.2, fix Doxygen warnings, modernize somewhat

doc/support/crashpad.doxy is updated with:

```
% doxygen -u doc/support/crashpad.doxy
[…]
% doxygen -v
1.13.2
```

Additional updates to doc/support/crashpad.doxy are made:
 - The settings for `DISABLE_INDEX` and `GENERATE_TREEVIEW` are updated,
   as Doxygen’s defaults have changed. This switches from the
   top-of-page index to the side-of-page tree view.
 - The TODO and Deprecated sections have become more prominent under the
   side-of-page tree view than they were with the top-of-page index, and
   they’re not very useful in Crashpad documentation, so they’re
   disabled by setting `GENERATE_TODOLIST` and `GENERATE_DEPRECATEDLIST`
   appropriately. The similar (but unused in Crashpad)
   `GENERATE_TESTLIST` and `GENERATE_BUGLIST` are also disabled.
 - `USE_DOT` is now set, to use `dot` from GraphViz to generate SVG
   diagrams. These look better than the PNGs that Doxygen generated
   without `dot`. `DOT_COMMON_ATTR` and `DOT_EDGE_ATTR` are set to make
   the fonts used in GraphViz-generated SVGs match those used in
   Doxygen-generated HTML/CSS.
 - `EXCLUDE` has been updated to drop directories that no longer exist
   (compat/non_cxx11_lib) and add ones that now do (compat/android,
   compat/ios, and compat/linux).
 - Some values that were otherwise unused in doc/support/crashpad.doxy
   are set back to their default values. The differences from the
   default configuration are shown with `doxygen -x
   doc/support/crashpad.doxy`, and a configuration template with default
   values can be generated for inspection with `doxygen -g
   /tmp/template.doxy`. The tags affected are:
    - `MATHJAX_RELPATH`, unused since `USE_MATHJAX` is `NO`.
    - `LATEX_CMD_NAME` and `LATEX_BIB_STYLE`, unused since `USE_LATEX`
      is `NO`).
    - `EXCLUDE_PATTERNS`, unused since `EXCLUDE_PATH` is empty.

doc/support/doxygen_crashpad.css is updated to change the non-monospaced
font from Open Sans to Noto Sans. It is also updated to use the CSS
properties Doxygen defines for the purpose, rather than monkeying around
with custom selectors. The properties can be discovered by running
`doxygen -w html header.html footer.html customdoxygen.css
doc/support/crashpad.doxy` and reviewing customdoxygen.css.

doc/support/generate.sh is updated to further execute
doc/support/generate_doxygen.py by invoking directly and relying on its
`#!/usr/bin/env python3` line rather than invoking via `python`, which
is no longer available on many systems. doc/support/generate_doxygen.py
has already been Python 3-compatible since f88a116c0e2e
(https://chromium-review.googlesource.com/c/3542572, 2022-03-23).

Finally, there are a number of changes to fix Doxygen warnings produced
by the new Doxygen version or because of new code that has not yet been
run through Doxygen during a test run.

Change-Id: I436688b16530cb0a07dbf89d32601fff689ac2f2
Reviewed-on: https://chromium-review.googlesource.com/c/crashpad/crashpad/+/6180234
Reviewed-by: Justin Cohen <justincohen@chromium.org>
Reviewed-by: Joshua Peraza <jperaza@chromium.org>
Commit-Queue: Mark Mentovai <mark@chromium.org>

client/crashpad_client.h

@@ -373,6 +373,9 @@ class CrashpadClient {
   //!     Arguments passed in other parameters and arguments required to perform
   //!     the handshake are the responsibility of this method, and must not be
   //!     specified in this parameter.
+  //! \param[in] attachments Attachment paths to pass to the Crashpad handler.
+  //!     The handler will be started with an `--attachment` argument for each
+  //!     path in this vector.
   //!
   //! \return `true` on success, `false` on failure with a message logged.
   bool StartHandlerAtCrash(
@@ -807,7 +810,7 @@ class CrashpadClient {
 #endif
 
  private:
-#if BUILDFLAG(IS_WIN)
+#if BUILDFLAG(IS_WIN) || DOXYGEN
   //!  \brief Registers process handlers for the client.
   void RegisterHandlers();
 #endif

client/ios_handler/in_process_intermediate_dump_handler.h

@@ -57,8 +57,8 @@ class InProcessIntermediateDumpHandler final {
   //!
   //! \param[in] writer The dump writer
   //! \param[in] system_data An object containing various system data points.
-  //! \param[in] report_time Report creation time in nanoseconds as returned by
+  //! \param[in] report_time_nanos Report creation time in nanoseconds as
-  //!     ClockMonotonicNanoseconds().
+  //!     returned by ClockMonotonicNanoseconds().
   static void WriteSystemInfo(IOSIntermediateDumpWriter* writer,
                               const IOSSystemDataCollector& system_data,
                               uint64_t report_time_nanos);
@@ -103,11 +103,10 @@ class InProcessIntermediateDumpHandler final {
   //! \brief Write an ExceptionSnapshot from a mach exception to the
   //!     intermediate dump.
   //!
-  //!  Only one of the WriteExceptionFromSignal, WriteExceptionFromMachException
+  //! Only one of the WriteExceptionFromSignal, WriteExceptionFromMachException
-  //!  and WriteExceptionFromNSException should be called per intermediate dump.
+  //! and WriteExceptionFromNSException should be called per intermediate dump.
   //!
   //! \param[in] writer The dump writer
-  //! \param[in] system_data An object containing various system data points.
   //! \param[in] behavior
   //! \param[in] thread
   //! \param[in] exception

client/ios_handler/prune_intermediate_dumps_and_crash_reports_thread.h

@@ -31,8 +31,8 @@ class PruneCondition;
 //!     dumps.
 //!
 //! After the thread is started, the database is pruned using the condition
-//! every 24 hours. Upon calling Start(), the thread waits 5 seconds before
+//! every 24 hours. Upon calling Start(), the thread waits before performing
-//! performing the initial prune operation.
+//! the initial prune operation.
 //!
 //! Locked intermediate dump files are unlocked only once, not periodically.
 //! Locked dumps that match this bundle id can be unlocked if they are over a
@@ -48,8 +48,11 @@ class PruneIntermediateDumpsAndCrashReportsThread
   //!     pruning.
   //! \param[in] pending_path The path to any locked intermediate dump files.
   //! \param[in] bundle_identifier_and_seperator The identifier for this client,
-  //!  used to determine when locked files are considered stale, with a
+  //!     used to determine when locked files are considered stale, with a
-  //!  seperator at the end to allow for substring searches.
+  //!     seperator at the end to allow for substring searches.
+  //! \param[in] is_extension Whether the process is an app extension. If
+  //!     `true`, the inital prune will occur after a 5-second delay. If
+  //!     `false`, the initial prune will occur after a 60-second delay.
   PruneIntermediateDumpsAndCrashReportsThread(
       CrashReportDatabase* database,
       std::unique_ptr<PruneCondition> condition,

doc/appengine/src/crashpad-home/main.go

@@ -146,11 +146,12 @@ func handler(w http.ResponseWriter, r *http.Request) {
 // contentType returns the appropriate content type header for file.
 func contentType(file string) string {
 	contentTypes := map[string]string{
-		".html": "text/html; charset=UTF-8",
 		".css":  "text/css; charset=UTF-8",
+		".html": "text/html; charset=UTF-8",
+		".ico":  "image/x-icon",
 		".js":   "text/javascript; charset=UTF-8",
 		".png":  "image/png",
-		".ico":  "image/x-icon",
+		".svg":  "image/svg+xml",
 	}
 	for suffix, typ := range contentTypes {
 		if strings.HasSuffix(file, suffix) {

doc/support/crashpad_doxygen.css

@@ -12,47 +12,27 @@
  * 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 url('https://fonts.googleapis.com/css2?family=Noto+Sans:ital,wght@0,100..900;1,100..900&display=swap');
-@import "https://fonts.googleapis.com/css?family=Source+Code+Pro";
+@import url('https://fonts.googleapis.com/css2?family=Source+Code+Pro:ital,wght@0,200..900;1,200..900&display=swap');
 
-body,
+:root {
-table,
+  --font-family-normal: 'Noto Sans',
-div,
+    'Lucida Grande',
-p,
+    'Lucida Sans Unicode',
-dl,
+    Helvetica,
-.title,
+    Arial,
-.icon,
+    sans-serif;
-table.directory,
+  --font-family-nav: var(--font-family-normal);
-.navpath li.navelem a,
+  --font-family-title: var(--font-family-normal);
-#projectname,
+  --font-family-toc: var(--font-family-normal);
-#projectbrief,
+  --font-family-search: var(--font-family-normal);
-#projectnumber,
+  --font-family-icon: var(--font-family-normal);
-div.toc li,
+  --font-family-tooltip: var(--font-family-normal);
-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,
+  --font-family-monospace: 'Source Code Pro',
-tt,
+    Monaco,
-pre.fragment,
+    'Lucida Console',
-div.line,
+    monospace;
-.overload,
-.params .paramdir,
-.sm-dox a span.sub-arrow {
-  font-family: 'Source Code Pro',
-               Monaco,
-               'Lucida Console',
-               monospace;
 }
 
 .icon {

doc/support/generate.sh

@@ -28,7 +28,7 @@ cd "$(dirname "${0}")/../.."
 
 source doc/support/compat.sh
 
-python doc/support/generate_doxygen.py
+doc/support/generate_doxygen.py
 
 output_dir=doc/generated
 maybe_mkdir "${output_dir}"

minidump/minidump_context.h

@@ -80,7 +80,7 @@ enum MinidumpContextX86Flags : uint32_t {
   //! \brief Indicates the validity of non-control integer registers
   //!     (`CONTEXT_INTEGER`).
   //!
-  //! The `edi`, `esi`, `ebx`, `edx`, `ecx, and `eax` fields are valid.
+  //! The `edi`, `esi`, `ebx`, `edx`, `ecx`, and `eax` fields are valid.
   kMinidumpContextX86Integer = kMinidumpContextX86 | 0x00000002,
 
   //! \brief Indicates the validity of non-control segment registers
@@ -122,10 +122,9 @@ enum MinidumpContextX86Flags : uint32_t {
 
   //! \brief Indicates the validity of all registers except `xsave` data.
   //!     (`CONTEXT_ALL`).
-  kMinidumpContextX86All = kMinidumpContextX86Full |
+  kMinidumpContextX86All =
-                           kMinidumpContextX86FloatingPoint |
+      kMinidumpContextX86Full | kMinidumpContextX86FloatingPoint |
-                           kMinidumpContextX86Debug |
+      kMinidumpContextX86Debug | kMinidumpContextX86Extended,
-                           kMinidumpContextX86Extended,
 };
 
 //! \brief A 32-bit x86 CPU context (register state) carried in a minidump file.
@@ -411,7 +410,7 @@ struct MinidumpXSaveAreaHeader {
 //! This is used to calculate the final size of the extended context, and
 //! can be validated by calling InitializeContext2 with one XSTATE feature,
 //! and LocateXStateFeature to determine the first offset.
-//! Also see "MANAGING STATE USING THE XSAVE FEATURE SET", Ch. 13, Intel SDM.
+//! Also see “MANAGING STATE USING THE XSAVE FEATURE SET”, Ch. 13, Intel SDM.
 constexpr uint32_t kMinidumpAMD64XSaveOffset = 0x550;
 
 //! \brief Offset of first xsave feature within the extended context area.
@@ -420,9 +419,9 @@ constexpr uint32_t kMinidumpAMD64XSaveOffset = 0x550;
 //! Intel SDM 13.4.1. This is not where the item is in the extended compacted
 //! context, but is the offset recorded in the minidump. It needs to be correct
 //! there. See https://windows-internals.com/cet-on-windows/ for some discussion
-//! "CONTEXT_XSTATE: Extended processor state chunk. The state is stored in the
+//! “CONTEXT_XSTATE: Extended processor state chunk. The state is stored in the
 //! same format the XSAVE operation stores it with exception of the first 512
-//! bytes, i.e. starting from XSAVE_AREA_HEADER." This may vary by cpuid.
+//! bytes, i.e. starting from XSAVE_AREA_HEADER.” This may vary by cpuid.
 constexpr uint32_t kXSaveAreaFirstOffset = 0x240;
 
 //! \brief XSAVE_CET_U_FORMAT

snapshot/ios/intermediate_dump_reader_util.h

@@ -73,9 +73,10 @@ const IOSIntermediateDumpList* GetListFromMap(const IOSIntermediateDumpMap* map,
 //!
 //! \param[in] map The map to load from.
 //! \param[in] key The key to load from \a map.
+//! \param[out] value The loaded string.
 //!
-//! \return Returns `true` if the string could be loaded, otherwise returns
+//! \return Returns `true` with \a value set accordingly if the string could be
-//!     `false` and logs an error.
+//!     loaded, otherwise returns `false` and logs an error.
 bool GetDataStringFromMap(const IOSIntermediateDumpMap* map,
                           const IntermediateDumpKey& key,
                           std::string* value);

snapshot/ios/memory_snapshot_ios_intermediate_dump.h

@@ -39,6 +39,7 @@ class MemorySnapshotIOSIntermediateDump final : public MemorySnapshot {
   //! \brief Initializes the object.
   //!
   //! \param[in] address The base address of the memory region to snapshot.
+  //! \param[in] data The destination address where the snapshot will be stored.
   //! \param[in] size The size of the memory region to snapshot.
   void Initialize(vm_address_t address, vm_address_t data, vm_size_t size);
 

snapshot/ios/module_snapshot_ios_intermediate_dump.h

@@ -46,8 +46,8 @@ class ModuleSnapshotIOSIntermediateDump final : public ModuleSnapshot {
 
   //! \brief Initialize the snapshot
   //!
-  //! \param[in] exception_data The intermediate dump map used to initialize
+  //! \param[in] image_data The intermediate dump map used to initialize this
-  //!     this object.
+  //!     object.
   //!
   //! \return `true` if the snapshot could be created.
   bool Initialize(const IOSIntermediateDumpMap* image_data);

snapshot/ios/system_snapshot_ios_intermediate_dump.h

@@ -44,7 +44,6 @@ class SystemSnapshotIOSIntermediateDump final : public SystemSnapshot {
   //!
   //! \param[in] system_data An intermediate dump map containing various system
   //!     data points.
-  //! \return `true` if the snapshot could be created.
   void Initialize(const IOSIntermediateDumpMap* system_data);
 
   // SystemSnapshot:

snapshot/linux/exception_snapshot_linux.h

@@ -53,6 +53,9 @@ class ExceptionSnapshotLinux final : public ExceptionSnapshot {
   //! \param[in] context_address The address in the target process' address
   //!     space of the ucontext_t passed to the signal handler.
   //! \param[in] thread_id The thread ID of the thread that received the signal.
+  //! \param[inout] gather_indirectly_referenced_memory_cap The remaining budget
+  //!     for indirectly referenced memory, honored on entry and updated on
+  //!     return.
   //!
   //! \return `true` if the snapshot could be created, `false` otherwise with
   //!     an appropriate message logged.

snapshot/linux/thread_snapshot_linux.h

@@ -44,6 +44,9 @@ class ThreadSnapshotLinux final : public ThreadSnapshot {
   //!     the thread.
   //! \param[in] thread The thread within the ProcessReaderLinux for
   //!     which the snapshot should be created.
+  //! \param[inout] gather_indirectly_referenced_memory_bytes_remaining The
+  //!     remaining budget for indirectly referenced memory, honored on entry
+  //!     and updated on return.
   //!
   //! \return `true` if the snapshot could be created, `false` otherwise with
   //!     a message logged.

snapshot/win/exception_snapshot_win.h

@@ -16,6 +16,7 @@
 #define CRASHPAD_SNAPSHOT_WIN_EXCEPTION_SNAPSHOT_WIN_H_
 
 #include <windows.h>
+
 #include <stdint.h>
 
 #include <memory>
@@ -63,6 +64,9 @@ class ExceptionSnapshotWin final : public ExceptionSnapshot {
   //! \param[in] exception_pointers The address of an `EXCEPTION_POINTERS`
   //!     record in the target process, passed through from the exception
   //!     handler.
+  //! \param[inout] gather_indirectly_referenced_memory_cap The remaining budget
+  //!     for indirectly referenced memory, honored on entry and updated on
+  //!     return.
   //!
   //! \note If the exception was triggered by
   //!     CrashpadClient::DumpAndCrashTargetProcess(), this has the side-effect

util/ios/ios_intermediate_dump_data.h

@@ -35,8 +35,7 @@ class IOSIntermediateDumpData : public IOSIntermediateDumpObject {
 
   //! \brief Constructs a new data object which owns a std::vector<uint8_t>.
   //!
-  //! \param[in] data An array of uint8_t.
+  //! \param[in] data A vector of uint8_t.
-  //! \param[in] length The length of \a data.
   IOSIntermediateDumpData(std::vector<uint8_t> data) : data_(std::move(data)) {}
 
   // IOSIntermediateDumpObject:

util/linux/scoped_ptrace_attach.h

@@ -17,7 +17,6 @@
 
 #include <sys/types.h>
 
-
 namespace crashpad {
 
 //! \brief Attaches to the process with process ID \a pid and blocks until the
@@ -35,7 +34,7 @@ bool PtraceAttach(pid_t pid, bool can_log = true);
 //! \param pid The process ID of the process to detach.
 //! \param can_log Whether this function may log messages on failure.
 //! \return `true` on success. `false` on failure with a message logged if \a
-//!     ca_log is `true `true`
+//!     can_log is `true`.
 bool PtraceDetach(pid_t pid, bool can_log = true);
 
 //! \brief Maintains a `ptrace()` attachment to a process.

util/mac/mac_util.h

@@ -52,8 +52,6 @@ int MacOSVersionNumber();
 //!     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 `"macOS 10.12.1 (16B2657)"`.
 //!
@@ -69,10 +67,10 @@ bool MacOSVersionComponents(int* major,
 
 //! \brief Returns the model name and board ID of the running system.
 //!
-//! \param[out] model The system’s model name. A mid-2012 15" MacBook Pro would
+//! \param[out] model The system’s model name. A mid-2012 15\" MacBook Pro would
 //!     report “MacBookPro10,1”.
-//! \param[out] board_id The system’s board ID. A mid-2012 15" MacBook Pro would
+//! \param[out] board_id The system’s board ID. A mid-2012 15\" MacBook Pro
-//!     report “Mac-C3EC7CD22292981F”.
+//!     would report “Mac-C3EC7CD22292981F”.
 //!
 //! If a value cannot be determined, its string is cleared.
 void MacModelAndBoard(std::string* model, std::string* board_id);