libgdiagnostics: doc fixes

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 <dmalcolm@redhat.com>

diff --git a/gcc/doc/libgdiagnostics/topics/compatibility.rst b/gcc/doc/libgdiagnostics/topics/compatibility.rst
index 10adcc516ce552b1f8f5815cc66a1a03874a9688..6d8c92f06ea2e05e3b70de03c5de515e74a40fd6 100644 (file)
--- 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 0390704963bd1fea88a763186b30c96b9ac88f02..c94d19e650979b76f719da960fb867dc50c18a20 100644 (file)
--- 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 184b563819109ed8900916b5cc562d465befffca..294d396f677c103800c4462a95de8aee83c81358 100644 (file)
--- 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 95b95ca117fb08b9def3eda7a84f0224e958a859..e64b668c24cf96abe949d43b7ef9e6c1ef7b7ffa 100644 (file)
--- 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::