Debian Codegraph @

gcc/doc/libgdiagnostics/topics/diagnostics.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 Diagnostics
21 ===========
22
23 .. type:: diagnostic
24
25 A :type:`diagnostic` is an opaque bundle of state for a particular
26 diagnostic that is being constructed in memory.
27
28
29 Lifecycle of a diagnostic
30 *************************
31
32 Diagnostics are
33
34 * *created* from a :type:`diagnostic_manager` by using
35 :func:`diagnostic_begin`, then
36
37 * *populated* with data, such as physical locations, logical locations,
38 metadata, execution paths, or fix-it hints, then
39
40 * *finished*, in which a formatting string and arguments are given,
41 via a call to :func:`diagnostic_finish` or :func:`diagnostic_finish_va`.
42 The :type:`diagnostic_manager` will emit the diagnostic to all of the
43 manager's output sinks (either immediately, or at some later time,
44 depending on the sink).
45
46 Once a :type:`diagnostic` has had one of these "finish" functions called
47 on it, it is freed, and is no longer valid for use.
48
49 The formatting strings use their own syntax; see :doc:`message-formatting`.
50
51 .. function:: diagnostic *diagnostic_begin (diagnostic_manager *diag_mgr, \
52 enum diagnostic_level level)
53
54 Create a new :type:`diagnostic` associated with the given
55 :type:`diagnostic_manager`.
56
57 The parameter ``diag_mgr`` must be non-NULL.
58
59 The parameter ``level`` describes the severity of the diagnostic.
60
61 .. enum:: diagnostic_level
62
63 This enum describes the severity of a particular diagnostic.
64
65 .. macro:: DIAGNOSTIC_LEVEL_ERROR
66
67 A problem sufficiently severe that the program cannot successfully
68 complete, or where the input being analyzed is definitely wrong
69 (e.g. malformed).
70
71 .. macro:: DIAGNOSTIC_LEVEL_WARNING
72
73 A problem where the input is technically correct, but is likely
74 not what the user intended, such as common mistakes, or other
75 unusual conditions that *may* indicate trouble, such as use of
76 obsolete features.
77
78 .. macro:: DIAGNOSTIC_LEVEL_NOTE
79
80 A supplementary message added to another :type:`diagnostic`, giving
81 extra information that may help the user understand it.
82
83 .. macro:: DIAGNOSTIC_LEVEL_SORRY
84
85 A problem where the input is valid, but the tool isn't
86 able to handle it.
87
88 .. function:: void diagnostic_finish (diagnostic *diag, const char *fmt, ...)
89
90 Emit ``diag`` to all sinks of its manager, and release ``diag``. It is not
91 valid to use ``diag`` after this call.
92
93 Use parameter ``fmt`` for the message.
94 Note that this uses gcc's pretty-print format, which is *not* printf.
95 See :doc:`message-formatting`.
96
97 Both ``diag`` and ``fmt`` must be non-NULL.
98
99 TODO: who is responsible for putting FMT through gettext?
100
101 .. function:: void diagnostic_finish_va (diagnostic *diag, const char *fmt, va_list *args)
102
103 This is equivalent to :func:`diagnostic_finish`, but using a
104 :type:`va_list` rather than directly taking variadic arguments.
105
106 All three parameters must be non-NULL.
107
108
109 Diagnostic groups
110 *****************
111
112 See :doc:`the "adding notes" section of the tutorial <../tutorial/04-notes>`
113 for an example of a diagnostic group.
114
115 .. function:: void diagnostic_manager_begin_group (diagnostic_manager *diag_mgr)
116
117 Begin a diagnostic group. All diagnostics emitted within
118 ``diag_mgr`` after the first one will be treated as additional information
119 relating to the initial diagnostic.
120
121 The parameter ``diag_mgr`` must be non-NULL.
122
123 .. function:: void diagnostic_manager_end_group (diagnostic_manager *diag_mgr)
124
125 Finish a diagnostic group.
126
127 The parameter ``diag_mgr`` must be non-NULL.