api-trace2.txt: elminate section describing the public trace2 API
Eliminate the mostly obsolete `Public API` sub-section from the `Trace2 API` section in the documentation. Strengthen the referral to `trace2.h`. Most of the technical information in this sub-section was moved to `trace2.h` in 6c51cb525d (trace2: move doc to trace2.h, 2019-11-17) to be adjacent to the function prototypes. The remaining text wasn't that useful by itself. Furthermore, the text would need a bit of overhaul to add routines that do not immediately generate a message, such as stopwatch timers. So it seemed simpler to just get rid of it. Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff Hostetler committed
Oct 24, 2022 at 13:41 UTC
8e8c5ad27a0a35f1be31af48050a8c81892c452d
1 file changed
+7
-54
Documentation/technical/api-trace2.txt
+7
-54
@@ -148,20 +148,18 @@ filename collisions).
148
149
== Trace2 API
150
151
-All public Trace2 functions and macros are defined in `trace2.h` and
152
-`trace2.c`. All public symbols are prefixed with `trace2_`.
151
+The Trace2 public API is defined and documented in `trace2.h`; refer to it for
152
+more information. All public functions and macros are prefixed
153
+with `trace2_` and are implemented in `trace2.c`.
154
155
There are no public Trace2 data structures.
156
157
The Trace2 code also defines a set of private functions and data types
158
in the `trace2/` directory. These symbols are prefixed with `tr2_`
158
-and should only be used by functions in `trace2.c`.
159
+and should only be used by functions in `trace2.c` (or other private
160
+source files in `trace2/`).
161
160
-== Conventions for Public Functions and Macros
161
-
162
-The functions defined by the Trace2 API are declared and documented
163
-in `trace2.h`. It defines the API functions and wrapper macros for
164
-Trace2.
162
+=== Conventions for Public Functions and Macros
163
164
Some functions have a `_fl()` suffix to indicate that they take `file`
165
and `line-number` arguments.
@@ -172,52 +170,7 @@ take a `va_list` argument.
170
Some functions have a `_printf_fl()` suffix to indicate that they also
171
take a `printf()` style format with a variable number of arguments.
172
175
-There are CPP wrapper macros and `#ifdef`s to hide most of these details.
176
-See `trace2.h` for more details. The following discussion will only
177
-describe the simplified forms.
178
-
179
-== Public API
180
-
181
-All Trace2 API functions send a message to all of the active
182
-Trace2 Targets. This section describes the set of available
183
-messages.
184
-
185
-It helps to divide these functions into groups for discussion
186
-purposes.
187
-
188
-=== Basic Command Messages
189
-
190
-These are concerned with the lifetime of the overall git process.
191
-e.g: `void trace2_initialize_clock()`, `void trace2_initialize()`,
192
-`int trace2_is_enabled()`, `void trace2_cmd_start(int argc, const char **argv)`.
193
-
194
-=== Command Detail Messages
195
-
196
-These are concerned with describing the specific Git command
197
-after the command line, config, and environment are inspected.
198
-e.g: `void trace2_cmd_name(const char *name)`,
199
-`void trace2_cmd_mode(const char *mode)`.
200
-
201
-=== Child Process Messages
202
-
203
-These are concerned with the various spawned child processes,
204
-including shell scripts, git commands, editors, pagers, and hooks.
205
-
206
-e.g: `void trace2_child_start(struct child_process *cmd)`.
207
-
208
-=== Git Thread Messages
209
-
210
-These messages are concerned with Git thread usage.
211
-
212
-e.g: `void trace2_thread_start(const char *thread_name)`.
213
-
214
-=== Region and Data Messages
215
-
216
-These are concerned with recording performance data
217
-over regions or spans of code. e.g:
218
-`void trace2_region_enter(const char *category, const char *label, const struct repository *repo)`.
219
-
220
-Refer to trace2.h for details about all trace2 functions.
173
+CPP wrapper macros are defined to hide most of these details.
174
175
== Trace2 Target Formats
176