From: Masami Hiramatsu (Google) <mhiramat@kernel.org>

Since traceprobe_parse_event_name() is a bit complicated, add a
kerneldoc for explaining the behavior.

Suggested-by: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
---
 kernel/trace/trace_probe.c |   17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/kernel/trace/trace_probe.c b/kernel/trace/trace_probe.c
index 9d26d901c9e5..7dcc4a548c69 100644
--- a/kernel/trace/trace_probe.c
+++ b/kernel/trace/trace_probe.c
@@ -247,7 +247,22 @@ int traceprobe_split_symbol_offset(char *symbol, long *offset)
 	return 0;
 }
 
-/* @buf must has MAX_EVENT_NAME_LEN size */
+/**
+ * traceprobe_parse_event_name - Parse a string into group and event names
+ * @pevent: A pointer to the string to be parsed. On return, this is updated
+ *          to point to the event name part of the string.
+ * @pgroup: A pointer to the group name. This is updated to point to the parsed
+ *          group name, which is stored in @buf.
+ * @buf:    A buffer to store the parsed group name.
+ * @offset: The offset of the string in the original user command, for logging.
+ *
+ * Description: This parses a string with the format `[GROUP/][EVENT]` or
+ *          `[GROUP.][EVENT]` (either GROUP or EVENT or both must be specified).
+ *          The parsed group name is stored in @buf.
+ *          The caller must ensure @buf is at least MAX_EVENT_NAME_LEN bytes.
+ *
+ * Return: 0 on success, or -EINVAL on failure.
+ */
 int traceprobe_parse_event_name(const char **pevent, const char **pgroup,
 				char *buf, int offset)
 {

On Wed, 23 Jul 2025 07:02:35 +0900
"Masami Hiramatsu (Google)" <mhiramat@kernel.org> wrote:

> From: Masami Hiramatsu (Google) <mhiramat@kernel.org>
> 
> Since traceprobe_parse_event_name() is a bit complicated, add a
> kerneldoc for explaining the behavior.
> 
> Suggested-by: Steven Rostedt <rostedt@goodmis.org>
> Signed-off-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
> ---
>  kernel/trace/trace_probe.c |   17 ++++++++++++++++-
>  1 file changed, 16 insertions(+), 1 deletion(-)
> 
> diff --git a/kernel/trace/trace_probe.c b/kernel/trace/trace_probe.c
> index 9d26d901c9e5..7dcc4a548c69 100644
> --- a/kernel/trace/trace_probe.c
> +++ b/kernel/trace/trace_probe.c
> @@ -247,7 +247,22 @@ int traceprobe_split_symbol_offset(char *symbol, long *offset)
>  	return 0;
>  }
>  
> -/* @buf must has MAX_EVENT_NAME_LEN size */
> +/**
> + * traceprobe_parse_event_name - Parse a string into group and event names
> + * @pevent: A pointer to the string to be parsed. On return, this is updated
> + *          to point to the event name part of the string.

I believe, these are supposed to be single lines. What it has on return
should be in the "Return" section below.

> + * @pgroup: A pointer to the group name. This is updated to point to the parsed
> + *          group name, which is stored in @buf.
> + * @buf:    A buffer to store the parsed group name.
> + * @offset: The offset of the string in the original user command, for logging.
> + *
> + * Description: This parses a string with the format `[GROUP/][EVENT]` or
> + *          `[GROUP.][EVENT]` (either GROUP or EVENT or both must be specified).
> + *          The parsed group name is stored in @buf.
> + *          The caller must ensure @buf is at least MAX_EVENT_NAME_LEN bytes.
> + *
> + * Return: 0 on success, or -EINVAL on failure.

So the Return section here should state what is returned in the parameters too.
Like:

 *    @pgroup is updated to point to the parsed group which is stored in @buf.

etc.

-- Steve



> + */
>  int traceprobe_parse_event_name(const char **pevent, const char **pgroup,
>  				char *buf, int offset)
>  {

On Tue, 22 Jul 2025 18:44:20 -0400
Steven Rostedt <rostedt@goodmis.org> wrote:

> On Wed, 23 Jul 2025 07:02:35 +0900
> "Masami Hiramatsu (Google)" <mhiramat@kernel.org> wrote:
> 
> > From: Masami Hiramatsu (Google) <mhiramat@kernel.org>
> > 
> > Since traceprobe_parse_event_name() is a bit complicated, add a
> > kerneldoc for explaining the behavior.
> > 
> > Suggested-by: Steven Rostedt <rostedt@goodmis.org>
> > Signed-off-by: Masami Hiramatsu (Google) <mhiramat@kernel.org>
> > ---
> >  kernel/trace/trace_probe.c |   17 ++++++++++++++++-
> >  1 file changed, 16 insertions(+), 1 deletion(-)
> > 
> > diff --git a/kernel/trace/trace_probe.c b/kernel/trace/trace_probe.c
> > index 9d26d901c9e5..7dcc4a548c69 100644
> > --- a/kernel/trace/trace_probe.c
> > +++ b/kernel/trace/trace_probe.c
> > @@ -247,7 +247,22 @@ int traceprobe_split_symbol_offset(char *symbol, long *offset)
> >  	return 0;
> >  }
> >  
> > -/* @buf must has MAX_EVENT_NAME_LEN size */
> > +/**
> > + * traceprobe_parse_event_name - Parse a string into group and event names
> > + * @pevent: A pointer to the string to be parsed. On return, this is updated
> > + *          to point to the event name part of the string.
> 
> I believe, these are supposed to be single lines. What it has on return
> should be in the "Return" section below.

Hmm, indeed. OK, I'll move it into Return section.

> 
> > + * @pgroup: A pointer to the group name. This is updated to point to the parsed
> > + *          group name, which is stored in @buf.

Ditto.

> > + * @buf:    A buffer to store the parsed group name.
> > + * @offset: The offset of the string in the original user command, for logging.
> > + *
> > + * Description: This parses a string with the format `[GROUP/][EVENT]` or
> > + *          `[GROUP.][EVENT]` (either GROUP or EVENT or both must be specified).
> > + *          The parsed group name is stored in @buf.
> > + *          The caller must ensure @buf is at least MAX_EVENT_NAME_LEN bytes.
> > + *
> > + * Return: 0 on success, or -EINVAL on failure.
> 
> So the Return section here should state what is returned in the parameters too.
> Like:
> 
>  *    @pgroup is updated to point to the parsed group which is stored in @buf.

OK, thanks!

> 
> etc.
> 
> -- Steve
> 
> 
> 
> > + */
> >  int traceprobe_parse_event_name(const char **pevent, const char **pgroup,
> >  				char *buf, int offset)
> >  {
> 


-- 
Masami Hiramatsu (Google) <mhiramat@kernel.org>