[v3,14/15] tools/lib/traceevent: Change description of few APIs
diff mbox series

Message ID 20181128090711.17792-15-tstoyanov@vmware.com
State Superseded
Headers show
Series
  • tools/lib/traceevent,tools/perf: Various changes in libtraceevent APIs
Related show

Commit Message

Tzvetomir Stoyanov Nov. 28, 2018, 9:07 a.m. UTC
APIs descriptions should describe the purpose of the
function, its parameters and return value. While working
on man pages implementation, I noticed mismatches in the
descriptions of few APIs. This patch changes the description
of these APIs, making them consistent with the man pages:
tep_print_num_field(), tep_print_func_field(),
tep_get_header_page_size(), tep_get_long_size(),
tep_set_long_size(), tep_get_page_size() and
tep_set_page_size().

Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
---
 tools/lib/traceevent/event-parse-api.c | 25 ++++++++++++++++---------
 tools/lib/traceevent/event-parse.c     |  4 ++--
 2 files changed, 18 insertions(+), 11 deletions(-)

Comments

Steven Rostedt Dec. 1, 2018, 3:43 a.m. UTC | #1
On Wed, 28 Nov 2018 09:07:46 +0000
Tzvetomir Stoyanov <tstoyanov@vmware.com> wrote:

> APIs descriptions should describe the purpose of the
> function, its parameters and return value. While working
> on man pages implementation, I noticed mismatches in the
> descriptions of few APIs. This patch changes the description
> of these APIs, making them consistent with the man pages:

BTW, you can have your descriptions be up to 76 characters in length.

> tep_print_num_field(), tep_print_func_field(),
> tep_get_header_page_size(), tep_get_long_size(),
> tep_set_long_size(), tep_get_page_size() and
> tep_set_page_size().
> 
> Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com>
> ---
>  tools/lib/traceevent/event-parse-api.c | 25 ++++++++++++++++---------
>  tools/lib/traceevent/event-parse.c     |  4 ++--
>  2 files changed, 18 insertions(+), 11 deletions(-)
> 
> diff --git a/tools/lib/traceevent/event-parse-api.c b/tools/lib/traceevent/event-parse-api.c
> index d4368dcc16ea..884b8585d22e 100644
> --- a/tools/lib/traceevent/event-parse-api.c
> +++ b/tools/lib/traceevent/event-parse-api.c
> @@ -100,10 +100,10 @@ tep_data2host8(struct tep_handle *pevent, unsigned long long data)
>  }
>  
>  /**
> - * tep_get_header_page_size - get size of the header page
> + * tep_get_header_page_size - get the size of a long integer, in kernel context
>   * @pevent: a handle to the tep_handle
>   *
> - * This returns size of the header page
> + * This returns the size of a long integer, in kernel context
>   * If @pevent is NULL, 0 is returned.
>   */
>  int tep_get_header_page_size(struct tep_handle *pevent)
> @@ -140,10 +140,12 @@ void tep_set_cpus(struct tep_handle *pevent, int cpus)
>  }
>  
>  /**
> - * tep_get_long_size - get the size of a long integer on the current machine
> + * tep_get_long_size - get the size of a long integer on the machine,
> + * 		       where the trace is generated

This follows kernel doc, which states that the above line must not be
more than one line. That's for the description below. Convert this to;

 /**
  * tep_get_long_size - get the size of a long integer on the traced machine

>   * @pevent: a handle to the tep_handle
>   *
> - * This returns the size of a long integer on the current machine
> + * This returns the size of a long integer on the machine,
> + * where the trace is generated
>   * If @pevent is NULL, 0 is returned.
>   */
>  int tep_get_long_size(struct tep_handle *pevent)
> @@ -154,7 +156,8 @@ int tep_get_long_size(struct tep_handle *pevent)
>  }
>  
>  /**
> - * tep_set_long_size - set the size of a long integer on the current machine
> + * tep_set_long_size - set the size of a long integer on the machine,
> + * 			where the trace is generated

This too: "on the traced machine"

>   * @pevent: a handle to the tep_handle
>   * @size: size, in bytes, of a long integer
>   *
> @@ -167,10 +170,12 @@ void tep_set_long_size(struct tep_handle *pevent, int long_size)
>  }
>  
>  /**
> - * tep_get_page_size - get the size of a memory page on the current machine
> + * tep_get_page_size - get the size of a memory page on the machine,
> + * 			where the trace is generated

This too.

>   * @pevent: a handle to the tep_handle
>   *
> - * This returns the size of a memory page on the current machine
> + * This returns the size of a memory page on the machine,
> + * where the trace is generated
>   * If @pevent is NULL, 0 is returned.
>   */
>  int tep_get_page_size(struct tep_handle *pevent)
> @@ -181,11 +186,13 @@ int tep_get_page_size(struct tep_handle *pevent)
>  }
>  
>  /**
> - * tep_set_page_size - set the size of a memory page on the current machine
> + * tep_set_page_size - set the size of a memory page on the machine,
> + * 			where the trace is generated

And this too.

>   * @pevent: a handle to the tep_handle
>   * @_page_size: size of a memory page, in bytes
>   *
> - * This sets the size of a memory page on the current machine
> + * This sets the size of a memory page on the machine,
> + * where the trace is generated
>   */
>  void tep_set_page_size(struct tep_handle *pevent, int _page_size)
>  {
> diff --git a/tools/lib/traceevent/event-parse.c b/tools/lib/traceevent/event-parse.c
> index 7b26b9e3a4ba..aed098f29b66 100644
> --- a/tools/lib/traceevent/event-parse.c
> +++ b/tools/lib/traceevent/event-parse.c
> @@ -6441,7 +6441,7 @@ int tep_get_any_field_val(struct trace_seq *s, struct tep_event *event,
>   * @record: The record with the field name.
>   * @err: print default error if failed.
>   *
> - * Returns: 0 on success, -1 field not found, or 1 if buffer is full.
> + * Returns: 1 on success, -1 field not found, or 0 if buffer is full.

Actually, it looks like it returns the length written on success.

>   */
>  int tep_print_num_field(struct trace_seq *s, const char *fmt,
>  			struct tep_event *event, const char *name,
> @@ -6473,7 +6473,7 @@ int tep_print_num_field(struct trace_seq *s, const char *fmt,
>   * @record: The record with the field name.
>   * @err: print default error if failed.
>   *
> - * Returns: 0 on success, -1 field not found, or 1 if buffer is full.
> + * Returns: 1 on success, -1 field not found, or 0 if buffer is full.

This too.

I applied the rest of this series except for this patch. If you want,
you can fix this patch up and resend it as a stand along (but label it
as v4).

Thanks!

-- Steve

>   */
>  int tep_print_func_field(struct trace_seq *s, const char *fmt,
>  			 struct tep_event *event, const char *name,
Steven Rostedt Dec. 1, 2018, 3:58 a.m. UTC | #2
On Fri, 30 Nov 2018 22:43:01 -0500
Steven Rostedt <rostedt@goodmis.org> wrote:

> > diff --git a/tools/lib/traceevent/event-parse.c b/tools/lib/traceevent/event-parse.c
> > index 7b26b9e3a4ba..aed098f29b66 100644
> > --- a/tools/lib/traceevent/event-parse.c
> > +++ b/tools/lib/traceevent/event-parse.c
> > @@ -6441,7 +6441,7 @@ int tep_get_any_field_val(struct trace_seq *s, struct tep_event *event,
> >   * @record: The record with the field name.
> >   * @err: print default error if failed.
> >   *
> > - * Returns: 0 on success, -1 field not found, or 1 if buffer is full.
> > + * Returns: 1 on success, -1 field not found, or 0 if buffer is full.  
> 
> Actually, it looks like it returns the length written on success.

And this actually changed by your update to trace_seq_printf() in patch
11.

Luckily, it appears that the only use cases just check for the -1. :-)

-- Steve

> 
> >   */
> >  int tep_print_num_field(struct trace_seq *s, const char *fmt,
> >  			struct tep_event *event, const char *name,
> > @@ -6473,7 +6473,7 @@ int tep_print_num_field(struct trace_seq *s, const char *fmt,
> >   * @record: The record with the field name.
> >   * @err: print default error if failed.
> >   *
> > - * Returns: 0 on success, -1 field not found, or 1 if buffer is full.
> > + * Returns: 1 on success, -1 field not found, or 0 if buffer is full.  
> 
> This too.
Steven Rostedt March 13, 2019, 3:56 p.m. UTC | #3
Ping.

-- Steve


On Fri, 30 Nov 2018 22:58:32 -0500
Steven Rostedt <rostedt@goodmis.org> wrote:

> On Fri, 30 Nov 2018 22:43:01 -0500
> Steven Rostedt <rostedt@goodmis.org> wrote:
> 
> > > diff --git a/tools/lib/traceevent/event-parse.c b/tools/lib/traceevent/event-parse.c
> > > index 7b26b9e3a4ba..aed098f29b66 100644
> > > --- a/tools/lib/traceevent/event-parse.c
> > > +++ b/tools/lib/traceevent/event-parse.c
> > > @@ -6441,7 +6441,7 @@ int tep_get_any_field_val(struct trace_seq *s, struct tep_event *event,
> > >   * @record: The record with the field name.
> > >   * @err: print default error if failed.
> > >   *
> > > - * Returns: 0 on success, -1 field not found, or 1 if buffer is full.
> > > + * Returns: 1 on success, -1 field not found, or 0 if buffer is full.    
> > 
> > Actually, it looks like it returns the length written on success.  
> 
> And this actually changed by your update to trace_seq_printf() in patch
> 11.
> 
> Luckily, it appears that the only use cases just check for the -1. :-)
> 
> -- Steve
> 
> >   
> > >   */
> > >  int tep_print_num_field(struct trace_seq *s, const char *fmt,
> > >  			struct tep_event *event, const char *name,
> > > @@ -6473,7 +6473,7 @@ int tep_print_num_field(struct trace_seq *s, const char *fmt,
> > >   * @record: The record with the field name.
> > >   * @err: print default error if failed.
> > >   *
> > > - * Returns: 0 on success, -1 field not found, or 1 if buffer is full.
> > > + * Returns: 1 on success, -1 field not found, or 0 if buffer is full.    
> > 
> > This too.

Patch
diff mbox series

diff --git a/tools/lib/traceevent/event-parse-api.c b/tools/lib/traceevent/event-parse-api.c
index d4368dcc16ea..884b8585d22e 100644
--- a/tools/lib/traceevent/event-parse-api.c
+++ b/tools/lib/traceevent/event-parse-api.c
@@ -100,10 +100,10 @@  tep_data2host8(struct tep_handle *pevent, unsigned long long data)
 }
 
 /**
- * tep_get_header_page_size - get size of the header page
+ * tep_get_header_page_size - get the size of a long integer, in kernel context
  * @pevent: a handle to the tep_handle
  *
- * This returns size of the header page
+ * This returns the size of a long integer, in kernel context
  * If @pevent is NULL, 0 is returned.
  */
 int tep_get_header_page_size(struct tep_handle *pevent)
@@ -140,10 +140,12 @@  void tep_set_cpus(struct tep_handle *pevent, int cpus)
 }
 
 /**
- * tep_get_long_size - get the size of a long integer on the current machine
+ * tep_get_long_size - get the size of a long integer on the machine,
+ * 		       where the trace is generated
  * @pevent: a handle to the tep_handle
  *
- * This returns the size of a long integer on the current machine
+ * This returns the size of a long integer on the machine,
+ * where the trace is generated
  * If @pevent is NULL, 0 is returned.
  */
 int tep_get_long_size(struct tep_handle *pevent)
@@ -154,7 +156,8 @@  int tep_get_long_size(struct tep_handle *pevent)
 }
 
 /**
- * tep_set_long_size - set the size of a long integer on the current machine
+ * tep_set_long_size - set the size of a long integer on the machine,
+ * 			where the trace is generated
  * @pevent: a handle to the tep_handle
  * @size: size, in bytes, of a long integer
  *
@@ -167,10 +170,12 @@  void tep_set_long_size(struct tep_handle *pevent, int long_size)
 }
 
 /**
- * tep_get_page_size - get the size of a memory page on the current machine
+ * tep_get_page_size - get the size of a memory page on the machine,
+ * 			where the trace is generated
  * @pevent: a handle to the tep_handle
  *
- * This returns the size of a memory page on the current machine
+ * This returns the size of a memory page on the machine,
+ * where the trace is generated
  * If @pevent is NULL, 0 is returned.
  */
 int tep_get_page_size(struct tep_handle *pevent)
@@ -181,11 +186,13 @@  int tep_get_page_size(struct tep_handle *pevent)
 }
 
 /**
- * tep_set_page_size - set the size of a memory page on the current machine
+ * tep_set_page_size - set the size of a memory page on the machine,
+ * 			where the trace is generated
  * @pevent: a handle to the tep_handle
  * @_page_size: size of a memory page, in bytes
  *
- * This sets the size of a memory page on the current machine
+ * This sets the size of a memory page on the machine,
+ * where the trace is generated
  */
 void tep_set_page_size(struct tep_handle *pevent, int _page_size)
 {
diff --git a/tools/lib/traceevent/event-parse.c b/tools/lib/traceevent/event-parse.c
index 7b26b9e3a4ba..aed098f29b66 100644
--- a/tools/lib/traceevent/event-parse.c
+++ b/tools/lib/traceevent/event-parse.c
@@ -6441,7 +6441,7 @@  int tep_get_any_field_val(struct trace_seq *s, struct tep_event *event,
  * @record: The record with the field name.
  * @err: print default error if failed.
  *
- * Returns: 0 on success, -1 field not found, or 1 if buffer is full.
+ * Returns: 1 on success, -1 field not found, or 0 if buffer is full.
  */
 int tep_print_num_field(struct trace_seq *s, const char *fmt,
 			struct tep_event *event, const char *name,
@@ -6473,7 +6473,7 @@  int tep_print_num_field(struct trace_seq *s, const char *fmt,
  * @record: The record with the field name.
  * @err: print default error if failed.
  *
- * Returns: 0 on success, -1 field not found, or 1 if buffer is full.
+ * Returns: 1 on success, -1 field not found, or 0 if buffer is full.
  */
 int tep_print_func_field(struct trace_seq *s, const char *fmt,
 			 struct tep_event *event, const char *name,