From c00c7382ddc1e3f2d773b14366023abf53ecce2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Tue, 13 Apr 2021 11:08:19 +0200 Subject: [PATCH 1/3] usage.c: don't copy/paste the same comment three times MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In ee4512ed481 (trace2: create new combined trace facility, 2019-02-22) we started with two copies of this comment, 0ee10fd1296 (usage: add trace2 entry upon warning(), 2020-11-23) added a third. Let's instead add an earlier comment that applies to all these mostly-the-same functions. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- usage.c | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/usage.c b/usage.c index 1b206de36d..c7d233b0de 100644 --- a/usage.c +++ b/usage.c @@ -55,12 +55,13 @@ static NORETURN void usage_builtin(const char *err, va_list params) exit(129); } +/* + * We call trace2_cmd_error_va() in the below functions first and + * expect it to va_copy 'params' before using it (because an 'ap' can + * only be walked once). + */ static NORETURN void die_builtin(const char *err, va_list params) { - /* - * We call this trace2 function first and expect it to va_copy 'params' - * before using it (because an 'ap' can only be walked once). - */ trace2_cmd_error_va(err, params); vreportf("fatal: ", err, params); @@ -70,10 +71,6 @@ static NORETURN void die_builtin(const char *err, va_list params) static void error_builtin(const char *err, va_list params) { - /* - * We call this trace2 function first and expect it to va_copy 'params' - * before using it (because an 'ap' can only be walked once). - */ trace2_cmd_error_va(err, params); vreportf("error: ", err, params); @@ -81,10 +78,6 @@ static void error_builtin(const char *err, va_list params) static void warn_builtin(const char *warn, va_list params) { - /* - * We call this trace2 function first and expect it to va_copy 'params' - * before using it (because an 'ap' can only be walked once). - */ trace2_cmd_error_va(warn, params); vreportf("warning: ", warn, params); From 4bf0c6f38f8a3dda532ab7e4b9b32d6c4bb925ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Tue, 13 Apr 2021 11:08:20 +0200 Subject: [PATCH 2/3] api docs: document BUG() in api-error-handling.txt MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When the BUG() function was added in d8193743e08 (usage.c: add BUG() function, 2017-05-12) these docs added in 1f23cfe0ef5 (doc: document error handling functions and conventions, 2014-12-03) were not updated. Let's do that. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/technical/api-error-handling.txt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Documentation/technical/api-error-handling.txt b/Documentation/technical/api-error-handling.txt index ceeedd485c..71486abb2f 100644 --- a/Documentation/technical/api-error-handling.txt +++ b/Documentation/technical/api-error-handling.txt @@ -1,8 +1,11 @@ Error reporting in git ====================== -`die`, `usage`, `error`, and `warning` report errors of various -kinds. +`BUG`, `die`, `usage`, `error`, and `warning` report errors of +various kinds. + +- `BUG` is for failed internal assertions that should never happen, + i.e. a bug in git itself. - `die` is for fatal application errors. It prints a message to the user and exits with status 128. From f6d25d7878901f0ec9b7a9c07c584911fc0da2ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Tue, 13 Apr 2021 11:08:21 +0200 Subject: [PATCH 3/3] api docs: document that BUG() emits a trace2 error event MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Correct documentation added in e544221d97a (trace2: Documentation/technical/api-trace2.txt, 2019-02-22) to state that calling BUG() also emits an "error" event. See ee4512ed481 (trace2: create new combined trace facility, 2019-02-22) for the initial implementation. The BUG() function did not emit an event then however, that was only changed later in 0a9dde4a04c (usage: trace2 BUG() invocations, 2021-02-05), that commit changed the code, but didn't update any of the docs. Let's also add a cross-reference from api-error-handling.txt. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/technical/api-error-handling.txt | 3 +++ Documentation/technical/api-trace2.txt | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/Documentation/technical/api-error-handling.txt b/Documentation/technical/api-error-handling.txt index 71486abb2f..8be4f4d0d6 100644 --- a/Documentation/technical/api-error-handling.txt +++ b/Documentation/technical/api-error-handling.txt @@ -23,6 +23,9 @@ various kinds. without running into too many problems. Like `error`, it returns -1 after reporting the situation to the caller. +These reports will be logged via the trace2 facility. See the "error" +event in link:api-trace2.txt[trace2 API]. + Customizable error handlers --------------------------- diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt index c65ffafc48..3f52f981a2 100644 --- a/Documentation/technical/api-trace2.txt +++ b/Documentation/technical/api-trace2.txt @@ -465,7 +465,7 @@ completed.) ------------ `"error"`:: - This event is emitted when one of the `error()`, `die()`, + This event is emitted when one of the `BUG()`, `error()`, `die()`, `warning()`, or `usage()` functions are called. + ------------