tracef.3.txt/tracelog.3.txt: always take variadic variants into account

This patch makes the `tracef.3.txt` and `tracelog.3.txt` manual page
sources always mention the variadic variant where the non-variadic
variant is mentioned for consistency.

This patch also changes the `va_list` type from the "SYNOPSIS" sections
as vtracef() and vtracelog() are macros. The type of the `ap` parameter
(`va_list`) is given in the "DESCRIPTION" sections.

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Change-Id: I84a795d16a39a483c43f1963189cd7e1faa5c329

diff --git a/doc/man/tracef.3.txt b/doc/man/tracef.3.txt
index 2894ca455af39e99c5d587dfd88272aab45a6cf0..cdd23aec49f8f8d1f345a66738da4cd6c74f6b42 100644 (file)
--- a/doc/man/tracef.3.txt
+++ b/doc/man/tracef.3.txt
@@ -15,31 +15,40 @@ SYNOPSIS
 
 [verse]
 #define *tracef*('fmt', ...)
-#define *vtracef*('fmt', 'va_list' ap)
+#define *vtracef*('fmt', 'ap')
 
 Link with `-llttng-ust`.
 
 
 DESCRIPTION
 -----------
-The LTTng-UST `tracef()` API allows you to trace your application with
-the help of a simple man:printf(3)-like macro. The 'fmt' argument is
-passed directly to the 'fmt' parameter of man:vasprintf(3), as well as
-the optional parameters following 'fmt'.
+The LTTng-UST `tracef()` and `vtracef()` API allows you to trace your
+application with the help of simple man:printf(3)-like and
+man:vprintf(3)-like macros.
 
-To use `tracef()` or `vtracef()`, include `<lttng/tracef.h>` where you need it,
-and link your application with `liblttng-ust`. See the <<example,EXAMPLE>>
-section below for a complete usage example.
+The 'fmt' argument is passed directly as the 'fmt' parameter of
+man:vasprintf(3), as well as:
 
-Once your application is instrumented with `tracef()` or `vtracef()` calls and
-ready to run, use man:lttng-enable-event(1) to enable the
+For `tracef()`::
+    The optional parameters following 'fmt'.
+
+For `vtracef()`::
+    The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
+    (`va_list` type).
+
+To use `tracef()` or `vtracef()`, include `<lttng/tracef.h>` where you
+need it, and link your application with `liblttng-ust`. See the
+<<example,EXAMPLE>> section below for a complete usage example.
+
+Once your application is instrumented with `tracef()` and/or `vtracef()`
+calls and ready to run, use man:lttng-enable-event(1) to enable the
 `lttng_ust_tracef:*` event.
 
-The `tracef()` events contain a single field, named `msg`, which is the
-formatted string output.
+The `tracef()` and `vtracef()` events contain a single field, named
+`msg`, which is the formatted string output.
 
-If you need to attach a specific log level to a `tracef()` call, use
-man:tracelog(3) instead.
+If you need to attach a specific log level to a `tracef()`/`vtracef()`
+call, use man:tracelog(3) and man:vtracelog(3) instead.
 
 See also the <<limitations,LIMITATIONS>> section below for important
 limitations to consider when using `tracef()` or `vtracef()`.
@@ -118,6 +127,7 @@ include::common-authors.txt[]
 SEE ALSO
 --------
 man:tracelog(3),
+man:vtracelog(3),
 man:lttng-ust(3),
 man:lttng(1),
 man:printf(3)

diff --git a/doc/man/tracelog.3.txt b/doc/man/tracelog.3.txt
index 8997f1171fe081545333bdd1fc36d893b94fc3f0..544d027a43888f2d20a7e41b0ce262d69fada9c6 100644 (file)
--- a/doc/man/tracelog.3.txt
+++ b/doc/man/tracelog.3.txt
@@ -15,37 +15,46 @@ SYNOPSIS
 
 [verse]
 #define *tracelog*('level', 'fmt', ...)
-#define *vtracelog*('level', 'fmt', 'va_list' ap)
+#define *vtracelog*('level', 'fmt', 'ap')
 
 Link with `-llttng-ust`.
 
 
 DESCRIPTION
 -----------
-The LTTng-UST `tracelog()` API allows you to trace your application with
-the help of a simple man:printf(3)-like macro, with an additional
-parameter for the desired log level. The 'fmt' argument is passed
-directly to the 'fmt' parameter of man:vasprintf(3), as well as
-the optional parameters following 'fmt'.
+The LTTng-UST `tracelog()` and `vtracelog()` API allows you to trace
+your application with the help of simple man:printf(3)-like and
+man:vprintf(3)-like macros, with an additional parameter for the desired
+log level.
 
-The purpose of `tracelog()` is to ease the migration from logging to
-tracing.
+The 'fmt' argument is passed directly as the 'fmt' parameter of
+man:vasprintf(3), as well as:
+
+For `tracelog()`::
+    The optional parameters following 'fmt'.
+
+For `vtracelog()`::
+    The 'ap' parameter as the 'ap' parameter of man:vasprintf(3)
+    (`va_list` type).
+
+The purpose of `tracelog()` and `vtracelog()` is to ease the migration
+from logging to tracing.
 
 The available values for the 'level' parameter are:
 
 include::log-levels.txt[]
 
-To use `tracelog()` or `vtracelog()`, include `<lttng/tracelog.h>` where you
-need it, and link your application with `liblttng-ust`.
-See the <<example,EXAMPLE>> section below for a complete usage example.
+To use `tracelog()` or `vtracelog()`, include `<lttng/tracelog.h>` where
+you need it, and link your application with `liblttng-ust`. See the
+<<example,EXAMPLE>> section below for a complete usage example.
 
-Once your application is instrumented with `tracelog()` calls and
-ready to run, use man:lttng-enable-event(1) to enable the
-`lttng_ust_tracelog:*` event. You can isolate specific log levels with
-the nloption:--loglevel and nloption:--loglevel-only options of this
-command.
+Once your application is instrumented with `tracelog()` and/or
+`vtracelog()` calls and ready to run, use man:lttng-enable-event(1) to
+enable the `lttng_ust_tracelog:*` event. You can isolate specific log
+levels with the nloption:--loglevel and nloption:--loglevel-only options
+of this command.
 
-The `tracelog()` events contain the following fields:
+The `tracelog()` and `vtracelog()` events contain the following fields:
 
 [options="header"]
 |===
@@ -64,8 +73,8 @@ The `tracelog()` events contain the following fields:
 |Formatted string output.
 |===
 
-If you do not need to attach a specific log level to a `tracelog()`
-call, use man:tracef(3) instead.
+If you do not need to attach a specific log level to a
+`tracelog()`/`vtracelog()` call, use man:tracef(3) instead.
 
 See also the <<limitations,LIMITATIONS>> section below for important
 limitations to consider when using `tracelog()` or `vtracelog()`.
@@ -162,6 +171,7 @@ include::common-authors.txt[]
 SEE ALSO
 --------
 man:tracef(3),
+man:vtracef(3),
 man:lttng-ust(3),
 man:lttng(1),
 man:printf(3)