On 9/18/26 5:27 PM, Kees Cook wrote:
> The kernel-doc in include/linux/seq_buf.h and lib/seq_buf.c documents
> the seq_buf interface, but no .rst file pulls either of them in, so none
> of it reaches the generated documentation.
>
> Add the missing kernel-doc for seq_buf_clear() and seq_buf_init(), and a
> Sequence Buffers section to the kernel API documentation. The static
> internal helper seq_buf_can_fit() is left out. Additionally fix
> seq_buf_hex_dump() indentation to avoid the reported Sphinx error:
>
> ERROR: Unexpected indentation.
> WARNING: Block quote ends without a blank line; unexpected unindent.
>
> Verified with "make SPHINXDIRS=core-api htmldocs", which rendered
> happily into core-api/kernel-api.html.
>
> Assisted-by: LLM
> Co-developed-by: Bill Wendling <[email protected]>
> Signed-off-by: Bill Wendling <[email protected]>
> Signed-off-by: Kees Cook <[email protected]>
Looks good. Thanks.
Tested-by: Randy Dunlap <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
> ---
> Cc: Jonathan Corbet <[email protected]>
> Cc: <[email protected]>
> Cc: "Matthew Wilcox (Oracle)" <[email protected]>
> Cc: Andrew Morton <[email protected]>
> Cc: Andy Shevchenko <[email protected]>
> Cc: Petr Mladek <[email protected]>
> Cc: Randy Dunlap <[email protected]>
> Cc: Shuah Khan <[email protected]>
> Cc: Steven Rostedt <[email protected]>
> ---
> Documentation/core-api/kernel-api.rst | 9 +++++++++
> include/linux/seq_buf.h | 12 ++++++++++++
> lib/seq_buf.c | 13 +++++++------
> 3 files changed, 28 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/core-api/kernel-api.rst
> b/Documentation/core-api/kernel-api.rst
> index 4c4a57c1c094..f5a0aedbbb48 100644
> --- a/Documentation/core-api/kernel-api.rst
> +++ b/Documentation/core-api/kernel-api.rst
> @@ -96,6 +96,15 @@ Error Pointers
> .. kernel-doc:: include/linux/err.h
> :internal:
>
> +Sequence Buffers
> +----------------
> +
> +.. kernel-doc:: include/linux/seq_buf.h
> + :internal:
> +
> +.. kernel-doc:: lib/seq_buf.c
> + :no-identifiers: seq_buf_can_fit
> +
> Sorting
> -------
>
> diff --git a/include/linux/seq_buf.h b/include/linux/seq_buf.h
> index 89d847d40626..416a8b67b9ad 100644
> --- a/include/linux/seq_buf.h
> +++ b/include/linux/seq_buf.h
> @@ -31,6 +31,10 @@ struct seq_buf {
> .size = SIZE, \
> }
>
> +/**
> + * seq_buf_clear - reset the seq_buf to be read / appended from the beginning
> + * @s: the seq_buf handle
> + */
> static inline void seq_buf_clear(struct seq_buf *s)
> {
> s->len = 0;
> @@ -38,6 +42,14 @@ static inline void seq_buf_clear(struct seq_buf *s)
> s->buffer[0] = '\0';
> }
>
> +/**
> + * seq_buf_init - initialize a seq_buf
> + * @s: the seq_buf handle
> + * @buf: pointer to the buffer
> + * @size: total size of @buf
> + *
> + * The contents of the buffer are ignored.
> + */
> static inline void
> seq_buf_init(struct seq_buf *s, char *buf, unsigned int size)
> {
> diff --git a/lib/seq_buf.c b/lib/seq_buf.c
> index 7e3bf837da01..1c86eae9e188 100644
> --- a/lib/seq_buf.c
> +++ b/lib/seq_buf.c
> @@ -407,12 +407,13 @@ int seq_buf_to_user(struct seq_buf *s, char __user
> *ubuf, size_t start, int cnt)
> *
> * Function is an analogue of print_hex_dump() and thus has similar
> interface.
> *
> - * linebuf size is maximal length for one line.
> - * 32 * 3 - maximum bytes per line, each printed into 2 chars + 1 for
> - * separating space
> - * 2 - spaces separating hex dump and ASCII representation
> - * 32 - ASCII representation
> - * 1 - terminating '\0'
> + * linebuf size is maximal length for one line::
> + *
> + * 32 * 3 - maximum bytes per line, each printed into 2 chars + 1 for
> + * separating space
> + * 2 - spaces separating hex dump and ASCII representation
> + * 32 - ASCII representation
> + * 1 - terminating '\0'
> *
> * Returns: zero on success, -1 on overflow.
> */
--
~Randy
