| Message ID | 20190325145017.30246-2-tstoyanov@vmware.com (mailing list archive) |
|---|---|
| State | Accepted |
| Headers | show |
| Series | Few patches, related to libtracevent APIs | expand |
On Mon, 25 Mar 2019 16:50:15 +0200 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: > 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(). Hi Tzvetomir, The above is very hard to read. Please list them one per line, and write it like this: 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() - tep_set_page_size() It's much easier on the eyes. I changed it for you. But next time, please start listing functions instead of stringing them in one hard to read bundle. Thanks! -- Steve > > Signed-off-by: Tzvetomir Stoyanov <tstoyanov@vmware.com> > --- > tools/lib/traceevent/event-parse-api.c | 20 ++++++++++---------- > tools/lib/traceevent/event-parse.c | 6 ++++-- > 2 files changed, 14 insertions(+), 12 deletions(-) > > diff --git a/tools/lib/traceevent/event-parse-api.c b/tools/lib/traceevent/event-parse-api.c > index d463761a58f4..3686a221e981 100644 > --- a/tools/lib/traceevent/event-parse-api.c > +++ b/tools/lib/traceevent/event-parse-api.c > @@ -43,8 +43,8 @@ int tep_get_events_count(struct tep_handle *tep) > * @flag: flag, or combination of flags to be set > * can be any combination from enum tep_flag > * > - * This sets a flag or mbination of flags from enum tep_flag > - */ > + * This sets a flag or combination of flags from enum tep_flag > + */ > void tep_set_flag(struct tep_handle *tep, int flag) > { > if(tep) > @@ -140,10 +140,10 @@ 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 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 traced machine > * If @pevent is NULL, 0 is returned. > */ > int tep_get_long_size(struct tep_handle *pevent) > @@ -154,11 +154,11 @@ 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 traced machine > * @pevent: a handle to the tep_handle > * @size: size, in bytes, of a long integer > * > - * This sets the size of a long integer on the current machine > + * This sets the size of a long integer on the traced machine > */ > void tep_set_long_size(struct tep_handle *pevent, int long_size) > { > @@ -167,10 +167,10 @@ 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 traced machine > * @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 traced machine > * If @pevent is NULL, 0 is returned. > */ > int tep_get_page_size(struct tep_handle *pevent) > @@ -181,11 +181,11 @@ 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 traced machine > * @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 traced machine > */ > 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 87494c7c619d..e53c566be55d 100644 > --- a/tools/lib/traceevent/event-parse.c > +++ b/tools/lib/traceevent/event-parse.c > @@ -6386,7 +6386,8 @@ 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 positive value on success, negative in case of an error, > + * 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, > @@ -6418,7 +6419,8 @@ 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 positive value on success, negative in case of an error, > + * 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,
diff --git a/tools/lib/traceevent/event-parse-api.c b/tools/lib/traceevent/event-parse-api.c index d463761a58f4..3686a221e981 100644 --- a/tools/lib/traceevent/event-parse-api.c +++ b/tools/lib/traceevent/event-parse-api.c @@ -43,8 +43,8 @@ int tep_get_events_count(struct tep_handle *tep) * @flag: flag, or combination of flags to be set * can be any combination from enum tep_flag * - * This sets a flag or mbination of flags from enum tep_flag - */ + * This sets a flag or combination of flags from enum tep_flag + */ void tep_set_flag(struct tep_handle *tep, int flag) { if(tep) @@ -140,10 +140,10 @@ 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 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 traced machine * If @pevent is NULL, 0 is returned. */ int tep_get_long_size(struct tep_handle *pevent) @@ -154,11 +154,11 @@ 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 traced machine * @pevent: a handle to the tep_handle * @size: size, in bytes, of a long integer * - * This sets the size of a long integer on the current machine + * This sets the size of a long integer on the traced machine */ void tep_set_long_size(struct tep_handle *pevent, int long_size) { @@ -167,10 +167,10 @@ 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 traced machine * @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 traced machine * If @pevent is NULL, 0 is returned. */ int tep_get_page_size(struct tep_handle *pevent) @@ -181,11 +181,11 @@ 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 traced machine * @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 traced machine */ 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 87494c7c619d..e53c566be55d 100644 --- a/tools/lib/traceevent/event-parse.c +++ b/tools/lib/traceevent/event-parse.c @@ -6386,7 +6386,8 @@ 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 positive value on success, negative in case of an error, + * 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, @@ -6418,7 +6419,8 @@ 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 positive value on success, negative in case of an error, + * 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,
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 | 20 ++++++++++---------- tools/lib/traceevent/event-parse.c | 6 ++++-- 2 files changed, 14 insertions(+), 12 deletions(-)