| 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. |