Re: [PATCH net-next v2 02/10] lib: Add a "stringset" data structure

[sashiko-bot@kernel.org]

Thank you for your contribution! Sashiko AI review found 1 potential
issue to consider:
- [Low] lib: stringset: malformed kernel-doc Return sections break
  htmldocs
--

commit 6b2f2a1d0a32f2df849790a6aef77082faf99b69
Author: Chuck Lever <cel@kernel.org>

lib: Add a "stringset" data structure

This commit introduces a sorted-array stringset data structure and API for
string membership testing and set intersection, along with its documentation.

> diff --git a/include/linux/stringset.h b/include/linux/stringset.h
> new file mode 100644
> index 0000000000000..fd41ea23f2b17
> --- /dev/null
> +++ b/include/linux/stringset.h

[ ... ]

> +/**
> + * stringset_add - Add a string to a stringset
> + * @set: An initialized stringset with available capacity
> + * @str: non-NULL string to be added to @set, in kmalloc'd memory
> + *
> + * On success, @str is now owned by @set and will be freed either
> + * by stringset_finalize() (if a content duplicate) or stringset_destroy().
> + * The stringset must have been allocated with sufficient capacity via
> + * stringset_alloc(). Strings must not be added after stringset_finalize()
> + * has been called. Callers must not hand the same pointer to stringset_add()
> + * more than once: ownership has already transferred, and a second add
> + * produces a double-free at stringset_destroy().
> + *
> + * Return:
> + *   %true: @str is now a member of @set
> + *   %false: @str could not be added (NULL, no capacity, or @set is
> + *           already finalized)
> + */

[Severity: Low]
Does the Return section here (and in stringset_add_dup() and
stringset_intersection()) need bullet markers (* %true: / * %false:)?

When Documentation/core-api/stringset.rst includes these kernel-doc
comments during make htmldocs, kdoc_parser strips the two leading spaces
after Return:, leaving two unindented lines (%true: and %false:) followed
by an indented continuation line without a preceding blank line or list
marker, which causes docutils to emit an "Unexpected indentation" error.
In the remaining multi-line Return sections (stringset_alloc(),
stringset_is_empty(), stringset_is_member(), and stringset_copy()),
omitting the list markers also causes the %true and %false descriptions to
collapse into a single paragraph in the rendered documentation.

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20261112-tls-session-tags-v2-0-a587a50de7fc@kernel.org?part=2