Successfully bootstrapped & regrtested on x86_64-pc-linux-gnu.
Pushed to trunk as r16-2208-g457464edf19f17.
gcc/ChangeLog:
* doc/libgdiagnostics/topics/compatibility.rst
(_LIBGDIAGNOSTICS_ABI_2): Add missing anchor.
* doc/libgdiagnostics/topics/diagnostic-manager.rst
(diagnostic_manager_add_sink_from_spec): Add links to GCC's
documentation of "-fdiagnostics-add-output=". Fix parameter
markup.
(diagnostic_manager_set_analysis_target): Fix parameter markup.
Add link to SARIF spec.
* doc/libgdiagnostics/topics/logical-locations.rst: Markup fix.
* doc/libgdiagnostics/tutorial/02-physical-locations.rst: Clarify
wording of what "the source file" means, and that a range can't
have multiple files.
Signed-off-by: David Malcolm <dmalc...@redhat.com>
---
.../libgdiagnostics/topics/compatibility.rst | 2 ++
.../topics/diagnostic-manager.rst | 26 +++++++++----------
.../topics/logical-locations.rst | 7 ++---
.../tutorial/02-physical-locations.rst | 11 ++++----
4 files changed, 25 insertions(+), 21 deletions(-)
diff --git a/gcc/doc/libgdiagnostics/topics/compatibility.rst
b/gcc/doc/libgdiagnostics/topics/compatibility.rst
index 10adcc516ce5..6d8c92f06ea2 100644
--- a/gcc/doc/libgdiagnostics/topics/compatibility.rst
+++ b/gcc/doc/libgdiagnostics/topics/compatibility.rst
@@ -178,6 +178,8 @@ acccessing values within a
:type:`diagnostic_logical_location`:
* :func:`diagnostic_logical_location_get_decorated_name`
+.. _LIBGDIAGNOSTICS_ABI_2:
+
``LIBGDIAGNOSTICS_ABI_2``
-------------------------
``LIBGDIAGNOSTICS_ABI_2`` covers the addition of these functions for
diff --git a/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst
b/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst
index 0390704963bd..c94d19e65097 100644
--- a/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst
+++ b/gcc/doc/libgdiagnostics/topics/diagnostic-manager.rst
@@ -63,17 +63,17 @@ Responsibilities include:
diagnostic_manager *control_mgr)
This function can be used to support option processing similar to GCC's
- :option:`-fdiagnostics-add-output=`. This allows command-line tools to
- support the same domain-specific language for specifying output sink
- as GCC does.
-
- The function will attempt to parse :param:`spec` as if it were
- an argument to GCC's :option:`-fdiagnostics-add-output=OUTPUT-SPEC`.
- If successful, it will add an output sink to :param:`affected_mgr` and
return zero.
- Otherwise, it will emit an error diagnostic to :param:`control_mgr` and
+ `-fdiagnostics-add-output=
<https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html#index-fdiagnostics-add-output>`_.
+ This allows command-line tools to support the same domain-specific
+ language for specifying output sinks as GCC does.
+
+ The function will attempt to parse ``spec`` as if it were
+ an argument to GCC's `-fdiagnostics-add-output=
<https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Message-Formatting-Options.html#index-fdiagnostics-add-output>`_.
+ If successful, it will add an output sink to ``affected_mgr`` and return
zero.
+ Otherwise, it will emit an error diagnostic to ``control_mgr`` and
return non-zero.
- :param:`affected_mgr` and :param:`control_mgr` can be the same manager,
+ ``affected_mgr`` and ``control_mgr`` can be the same manager,
or be different managers.
This function was added in :ref:`LIBGDIAGNOSTICS_ABI_2`; you can
@@ -83,14 +83,14 @@ Responsibilities include:
#ifdef LIBDIAGNOSTICS_HAVE_diagnostic_manager_add_sink_from_spec
-
.. function:: void diagnostic_manager_set_analysis_target (diagnostic_manager
*mgr, \
const
diagnostic_file *file)
- This function sets the "main input file" of :param:`mgr` to be
- :param:`file`.
+ This function sets the "main input file" of ``mgr`` to be
+ ``file``.
This affects the :code:`<title>` of generated HTML and
- the :code:`role` of the artifact in SARIF output (SARIF v2.1.0 section
3.24.6).
+ the :code:`role` of the :code:`artifact` in SARIF output
+ (`SARIF v2.1.0 section 3.24.6
<https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790867>`_).
This function was added in :ref:`LIBGDIAGNOSTICS_ABI_2`; you can
test for its presence using
diff --git a/gcc/doc/libgdiagnostics/topics/logical-locations.rst
b/gcc/doc/libgdiagnostics/topics/logical-locations.rst
index 184b56381910..294d396f677c 100644
--- a/gcc/doc/libgdiagnostics/topics/logical-locations.rst
+++ b/gcc/doc/libgdiagnostics/topics/logical-locations.rst
@@ -120,7 +120,7 @@ source location
"equal" input values on the same :type:`diagnostic_manager` will return
the same instance of :type:`diagnostic_logical_location`. "Equal" here
includes different string buffers that compare as equal with
- :func:``strcmp`.
+ :func:`strcmp`.
.. function:: void diagnostic_manager_debug_dump_logical_location (const
diagnostic_manager *diag_mgr, \
const
diagnostic_logical_location *loc, \
@@ -147,8 +147,9 @@ Accessors
The following functions can be used to access the data that was passed to a
:type:`diagnostic_logical_location` when it was created. In each case, the
-``loc`` parameter must be non-NULL. :type:`const char *` values will point
-at copies of the original buffer.
+``loc`` parameter must be non-NULL. The return values will point
+at *copies* of the original buffer owned by the
+:type:`diagnostic_logical_location`, or be null.
.. function:: enum diagnostic_logical_location_kind_t
diagnostic_logical_location_get_kind (const diagnostic_logical_location *loc)
diff --git a/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst
b/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst
index 95b95ca117fb..e64b668c24cf 100644
--- a/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst
+++ b/gcc/doc/libgdiagnostics/tutorial/02-physical-locations.rst
@@ -112,10 +112,10 @@ leading to output like this::
foo.c:17: error: can't find 'foo.h'"
17 | #include <foo.h>
-where libgdiagnostics will attempt to load the source file and
+where libgdiagnostics will attempt to load ``foo.c`` and
quote the pertinent line.
-If libgdiagnostics cannot open the file, it will merely print::
+If libgdiagnostics cannot open ``foo.c``, it will merely print::
foo.c:17: error: can't find 'foo.h'
@@ -160,14 +160,15 @@ On compiling and running the program, we should get this
output::
17 | #include <foo.h>
| ^~~~~
-where libgdiagnostics will attempt to load the source file and
+where libgdiagnostics will attempt to load ``foo.c`` and
underling the pertinent part of the given line.
-If libgdiagnostics cannot open the file, it will merely print::
+If libgdiagnostics cannot open ``foo.c``, it will merely print::
foo.c:17:8: error: can't find 'foo.h'
-A range can span multiple lines within the same file.
+A range can span multiple lines within the same file, but cannot
+span multiple files.
As before, you can use :func:`diagnostic_manager_debug_dump_location` to
dump the locations. For the above example::
--
2.26.3
