Debian Codegraph @

gcc/doc/libgdiagnostics/tutorial/04-notes.rst

raw
1 .. Copyright (C) 2024-2025 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <[email protected]>
3
4 This is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
8
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see
16 <https://www.gnu.org/licenses/>.
17
18 .. default-domain:: c
19
20 Tutorial part 4: adding notes
21 =============================
22
23 Let's further extend the previous example to add a "note" to it.
24
25 We want to generate output like this::
26
27 test-with-note.c:17:11: error: can't find 'foo.h'
28 17 | #include <foo.h>
29 | ^~~~~
30 test-with-note.c:17:11: note: have you looked behind the couch?
31
32 The "error" and "note" are both instances of :type:`diagnostic`.
33 We want to let libgdiagnostics know that they are grouped together.
34 The way to do this is to use :func:`diagnostic_manager_begin_group`
35 and :func:`diagnostic_manager_end_group` around the "finish" calls
36 to the diagnostics.
37
38 .. literalinclude:: ../../../testsuite/libgdiagnostics.dg/test-error-with-note.c
39 :language: c
40 :start-after: /* begin quoted source */
41 :end-before: /* end quoted source */
42
43 On compiling and running the program, we should get the desired output::
44
45 test-with-note.c:17:11: error: can't find 'foo.h'
46 17 | #include <foo.h>
47 | ^~~~~
48 test-with-note.c:17:11: note: have you looked behind the couch?
49
50 The grouping doesn't affect text output sinks, but a
51 :doc:`SARIF sink <../topics/sarif>` will group the note within the error
52 (via the ``relatedLocations`` property of ``result`` objects; see SARIF v2.1.0
53 `ยง3.27.22 <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790910>`_).
54
55 In the above, the note had the same physical location as the error
56 (``loc_range``). This can be useful for splitting up a message into two
57 parts to make localization easier, but they could have different locations, such
58 as in::
59
60 test.xml:10:2: error: 'foo' is not valid here
61 test.xml:5:1: note: within element 'bar'
62
63 where each :type:`diagnostic` had its own :type:`diagnostic_physical_location`.
64
65 In :doc:`the next tutorial <05-warnings>` we'll look at issuing warnings,
66 rather than errors.