Re: [PATCH v4 27/46] tools/lib/traceevent: Man pages for tep_filter_alloc(), tep_filter_free() and tep_filter_reset()

[Steven Rostedt <rostedt@goodmis.org>]

On Fri,  8 Mar 2019 15:36:35 +0200
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:

> Create man pages tep_filter_alloc(), tep_filter_free() and tep_filter_reset()
> as part of the libtraceevent APIs.
> 
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
>  .../Documentation/libtraceevent-filter.txt    | 85 +++++++++++++++++++
>  1 file changed, 85 insertions(+)
>  create mode 100644 tools/lib/traceevent/Documentation/libtraceevent-filter.txt
> 
> diff --git a/tools/lib/traceevent/Documentation/libtraceevent-filter.txt b/tools/lib/traceevent/Documentation/libtraceevent-filter.txt
> new file mode 100644
> index 000000000000..6335bcc10c6c
> --- /dev/null
> +++ b/tools/lib/traceevent/Documentation/libtraceevent-filter.txt
> @@ -0,0 +1,85 @@
> +libtraceevent(3)
> +================
> +
> +NAME
> +----
> +tep_filter_alloc,tep_filter_free,tep_filter_reset - Create / free / reset an event filter.
> +
> +SYNOPSIS
> +--------
> +[verse]
> +--
> +*#include <event-parse.h>*
> +
> +struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_);
> +void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_);
> +void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_);
> +--
> +
> +DESCRIPTION
> +-----------
> +The _tep_filter_alloc()_ function creates a new event filter. The _tep_ argument
> +is the trace event parser context.

We need more description on what a filter is. Hmm, perhaps we should
make all the filter functions in one man page. This way the one man
page can show how filters are used.

That is, combine this patch with the next 4 patches.

-- Steve

> +
> +The _tep_filter_free()_ function frees an event filter and all resources that it
> +had used.
> +
> +The _tep_filter_reset()_ function removes all rules from an event filter and
> +resets it.
> +
> +RETURN VALUE
> +------------
> +The _tep_filter_alloc()_ function returns a pointer to the newly created event
> +filter, or NULL in case of an error.
> +
> +EXAMPLE
> +-------
> +[source,c]
> +--
> +#include <event-parse.h>
> +...
> +struct tep_handle *tep = tep_alloc();
> +...
> +struct tep_event_filter *filter = tep_filter_alloc(tep);
> +if (filter == NULL) {
> +	/* Failed to create the filter */
> +}
> +...
> +tep_filter_reset(filter);
> +...
> +tep_filter_free(filter);
> +...
> +--
> +
> +FILES
> +-----
> +[verse]
> +--
> +*event-parse.h*
> +	Header file to include in order to have access to the library APIs.
> +*-ltraceevent*
> +	Linker switch to add when building a program that uses the library.
> +--
> +
> +SEE ALSO
> +--------
> +_libtraceevent(3)_, _trace-cmd(1)_
> +
> +AUTHOR
> +------
> +[verse]
> +--
> +*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
> +*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
> +--
> +REPORTING BUGS
> +--------------
> +Report bugs to  <linux-trace-devel@vger.kernel.org>
> +
> +LICENSE
> +-------
> +libtraceevent is Free Software licensed under the GNU LGPL 2.1
> +
> +RESOURCES
> +---------
> +https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git