Debian Codegraph @

gcc/doc/libgdiagnostics/topics/fix-it-hints.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 Fix-it hints
21 ============
22
23 Adding fix-it hints to a diagnostic
24 ***********************************
25
26 A :type:`diagnostic` can contain "fix-it hints", giving suggestions
27 for the user on how to edit their code to fix a problem. These
28 can be expressed as insertions, replacements, and removals of text.
29
30 There is only limited support for newline characters in fix-it hints:
31 only hints with newlines which insert an entire new line are permitted,
32 inserting at the start of a line, and finishing with a newline
33 (with no interior newline characters). Other attempts to add
34 fix-it hints containing newline characters will fail.
35 Similarly, attempts to delete or replace a range *affecting* multiple
36 lines will fail.
37
38 The API handles these failures gracefully, so that diagnostics can attempt
39 to add fix-it hints without each needing extensive checking.
40
41 Fix-it hints are printed to text sinks, and are emitted by SARIF sinks
42 as ``fix`` objects (see SARIF 2.1.0
43 `ยง3.55 fix object <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141791131>`_).
44
45 Fix-it hints within a :type:`diagnostic` are "atomic": if any hints can't
46 be applied, none of them will be, and no fix-its hints will be displayed
47 for that diagnostic. This implies that diagnostic messages need to be worded
48 in such a way that they make sense whether or not the fix-it hints
49 are displayed.
50
51 All fix-it hints within one :type:`diagnostic` must affect the same
52 :type:`diagnostic_file`.
53
54 .. function:: void diagnostic_add_fix_it_hint_insert_before (diagnostic *diag, \
55 const diagnostic_physical_location *loc, \
56 const char *addition)
57
58 Add a fix-it hint to ``diag`` suggesting the insertion of the string
59 ``addition`` before ``LOC``.
60
61 For example::
62
63 ptr = arr[0];
64 ^~~~~~
65 &
66
67 This :type:`diagnostic` has a single location covering ``arr[0]``,
68 with the caret at the start. It has a single insertion fix-it hint,
69 inserting ``&`` before the start of ``loc``.
70
71 .. function:: void diagnostic_add_fix_it_hint_insert_after (diagnostic *diag, \
72 const diagnostic_physical_location *loc, \
73 const char *addition)
74
75 Add a fix-it hint to ``diag`` suggesting the insertion of the string
76 ``addition`` after the end of ``LOC``.
77
78 For example, in::
79
80 #define FN(ARG0, ARG1, ARG2) fn(ARG0, ARG1, ARG2)
81 ^~~~ ^~~~ ^~~~
82 ( ) ( ) ( )
83
84
85 the :type:`diagnostic` has three physical locations, covering ``ARG0``,
86 ``ARG1``, and ``ARG2``, and 6 insertion fix-it hints: each arg
87 has a pair of insertion fix-it hints, suggesting wrapping
88 them with parentheses: one a '(' inserted before,
89 the other a ')' inserted after.
90
91 .. function:: void diagnostic_add_fix_it_hint_replace (diagnostic *diag, \
92 const diagnostic_physical_location *loc, \
93 const char *replacement)
94
95 Add a fix-it hint to ``diag`` suggesting the replacement of the text
96 at ``LOC`` with the string ``replacement``.
97
98 For example, in::
99
100 c = s.colour;
101 ^~~~~~
102 color
103
104 This :type:`diagnostic` has a single physical location covering ``colour``,
105 and a single "replace" fix-it hint, covering the same range, suggesting
106 replacing it with ``color``.
107
108 .. function:: void diagnostic_add_fix_it_hint_delete (diagnostic *diag, \
109 const diagnostic_physical_location *loc)
110
111 Add a fix-it hint to ``diag`` suggesting the deletion of the text
112 at ``LOC``.
113
114
115 For example, in::
116
117 struct s {int i};;
118 ^
119 -
120
121 This :type:`diagnostic` has a single physical location at the stray
122 trailing semicolon, along with a single removal fix-it hint, covering
123 the same location.
124
125
126 Generating patches
127 ******************
128
129 .. function:: void diagnostic_manager_write_patch (diagnostic_manager *diag_mgr, \
130 FILE *dst_stream)
131
132 Write a patch to ``dst_stream`` consisting of the effect of all fix-it hints
133 on all diagnostics that have been finished on ``diag_mgr``.
134
135 Both parameters must be non-NULL.