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>
sed -i '' -E -e 's/Copyright (.+) The Crashpad Authors\. All rights reserved\.$/Copyright \1 The Crashpad Authors/' $(git grep -El 'Copyright (.+) The Crashpad Authors\. All rights reserved\.$')
Bug: chromium:1098010
Change-Id: I8d6138469ddbe3d281a5d83f64cf918ec2491611
Reviewed-on: https://chromium-review.googlesource.com/c/crashpad/crashpad/+/3878262
Reviewed-by: Joshua Peraza <jperaza@chromium.org>
Commit-Queue: Mark Mentovai <mark@chromium.org>
This makes it easier to generate Doxygen documentation on Windows.
Change-Id: I14c203d2618d8321d5a94d836de434bbaa21c3c9
Reviewed-on: https://chromium-review.googlesource.com/461403
Reviewed-by: Scott Graham <scottmg@chromium.org>
This makes Doxygen’s output more actionable by setting QUIET = YES to
suppress verbose progress spew, and WARN_IF_UNDOCUMENTED = NO to prevent
warnings for undocumented classes and members from being generated. The
latter is too noisy, producing 721 warnings in the current codebase.
The remaining warnings produced by Doxygen were useful and actionable.
They fell into two categories: abuses of Doxygen’s markup syntax, and
missing (or misspelled) parameter documentation. In a small number of
cases, pass-through parameters had intentionally been left undocumented.
In these cases, they are now given blank \param descriptions. This is
not optimal, but there doesn’t appear to be any other way to tell
Doxygen to allow a single parameter to be undocumented.
Some tricky Doxygen errors were resolved by asking it to not enter
directiores that we do not provide documentation in (such as the
“on-platform” compat directories, compat/mac and compat/win, as well as
compat/non_cxx11_lib) while allowing it to enter the
“off-platform” directories that we do document (compat/non_mac and
compat/non_win).
A Doxygen run (doc/support/generate_doxygen.sh) now produces no output
at all. It would produce warnings if any were triggered.
Not directly related, but still relevant to documentation,
doc/support/generate.sh is updated to remove temporary removals of
now-extinct files and directories. doc/appengine/README is updated so
that a consistent path to “goapp” is used throughout the file.
Change-Id: I300730c04de4d3340551ea3086ca70cc5ff862d1
Reviewed-on: https://chromium-review.googlesource.com/408812
Reviewed-by: Robert Sesek <rsesek@chromium.org>
The generated page’s benefit-to-complexity ratio was too low.
BUG=crashpad:138
Change-Id: I5324c33b6b7f83e973c40b256b06e25c763b23c4
Reviewed-on: https://chromium-review.googlesource.com/408268
Reviewed-by: Robert Sesek <rsesek@chromium.org>
Most of the world, including the Chromium universe, seems to be
standardizing on Markdown for documentation. Markdown provides the
benefit of automatic rendering on Gitiles (Gerrit), and on GitHub
mirrors as well. Crashpad should fit in with its surroundings.
There are two quirks that I was unable to resolve.
- Markdown does not allow **emphasis** within a ```code fence```
region. In blocks showing interactive examples, the AsciiDoc
documentation used this to highlight what the user was expected to
type.
- Markdown does not have a “definition list” (<dl>). This would have
been nice in man pages for the Options and Exit Status sections.
In its place, I used unnumbered lists. This is a little ugly, but
it’s not the end of the world.
The new Markdown-formatted documentation is largely identical to the
AsciiDoc that it replaces. Minor editorial revisions were made.
References to Mac OS X now mention macOS, and tool man pages describing
tools that that access task ports now mention System Integrity
Protection (SIP).
The AppEngine-based https://crashpad.chromium.org/ app in doc/appengine
is still necessary to serve Doxygen-generated documentation. This app is
updated to redirect existing generated-HTML URLs to Gitiles’ automatic
Markdown rendering.
Scripts in doc/support are updated to adapt to this change. All AsciiDoc
support files in doc/support have been removed.
BUG=crashpad:138
Change-Id: I15ad423d5b7aa1b7aa2ed1d2cb72639eec7c81aa
Reviewed-on: https://chromium-review.googlesource.com/408256
Reviewed-by: Robert Sesek <rsesek@chromium.org>
Reviewed-by: Scott Graham <scottmg@chromium.org>
This script populates doc/generated. This directory is named in
.gitignore on the master branch, but will not be ignored on the doc
branch. The plan is to merge master into doc and run this script to
generate and check in a new set of generated docs.
BUG=crashpad:67
R=rsesek@chromium.org
Review URL: https://codereview.chromium.org/1397683003 .
