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>
---
 Changes in v4:
  - Move longer parameter description into Return section.
  - Rewrite the style according to
    Documentation/doc-guide/kernel-doc.rst
---
 kernel/trace/trace_probe.c |   20 +++++++++++++++++++-
 1 file changed, 19 insertions(+), 1 deletion(-)

diff --git a/kernel/trace/trace_probe.c b/kernel/trace/trace_probe.c
index 9d26d901c9e5..4fb3d98e38ea 100644
--- a/kernel/trace/trace_probe.c
+++ b/kernel/trace/trace_probe.c
@@ -247,7 +247,25 @@ 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.
+ * @pgroup: A pointer to the group name.
+ * @buf:    A buffer to store the parsed group name.
+ * @offset: The offset of the string in the original user command, for logging.
+ *
+ * This parses a string with the format `[GROUP/][EVENT]` or `[GROUP.][EVENT]`
+ * (either GROUP or EVENT or both must be specified).
+ * Since 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.
+ *
+ * If success, *@pevent is updated to point to the event name part of the
+ * original string, or NULL if there is no event name.
+ * Also, *@pgroup is updated to point to the parsed group which is stored
+ * in @buf, or NULL if there is no group name.
+ */
 int traceprobe_parse_event_name(const char **pevent, const char **pgroup,
 				char *buf, int offset)
 {

On Wed, 23 Jul 2025 10:31:45 +0900
"Masami Hiramatsu (Google)" <mhiramat@kernel.org> wrote:

> -/* @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.
> + * @pgroup: A pointer to the group name.
> + * @buf:    A buffer to store the parsed group name.
> + * @offset: The offset of the string in the original user command, for logging.
> + *
> + * This parses a string with the format `[GROUP/][EVENT]` or `[GROUP.][EVENT]`
> + * (either GROUP or EVENT or both must be specified).
> + * Since 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.
> + *
> + * If success, *@pevent is updated to point to the event name part of the
> + * original string, or NULL if there is no event name.
> + * Also, *@pgroup is updated to point to the parsed group which is stored
> + * in @buf, or NULL if there is no group name.
> + */
>  int traceprobe_parse_event_name(const char **pevent, const char **pgroup,
>  				char *buf, int offset)
>  {

Much better.

Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>

-- Steve

On Wed, 23 Jul 2025 10:00:49 -0400
Steven Rostedt <rostedt@goodmis.org> wrote:

> On Wed, 23 Jul 2025 10:31:45 +0900
> "Masami Hiramatsu (Google)" <mhiramat@kernel.org> wrote:
> 
> > -/* @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.
> > + * @pgroup: A pointer to the group name.
> > + * @buf:    A buffer to store the parsed group name.
> > + * @offset: The offset of the string in the original user command, for logging.
> > + *
> > + * This parses a string with the format `[GROUP/][EVENT]` or `[GROUP.][EVENT]`
> > + * (either GROUP or EVENT or both must be specified).
> > + * Since 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.
> > + *
> > + * If success, *@pevent is updated to point to the event name part of the
> > + * original string, or NULL if there is no event name.
> > + * Also, *@pgroup is updated to point to the parsed group which is stored
> > + * in @buf, or NULL if there is no group name.
> > + */
> >  int traceprobe_parse_event_name(const char **pevent, const char **pgroup,
> >  				char *buf, int offset)
> >  {
> 
> Much better.
> 
> Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>

Thank you! Let me pick the series in probes/for-next.


> 
> -- Steve
> 


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