Re: [PATCH v2 9/9] docs: core-api: Document the seq_buf API

[Randy Dunlap]

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 <morbo@xxxxxxxxxx>
> Signed-off-by: Bill Wendling <morbo@xxxxxxxxxx>
> Signed-off-by: Kees Cook <kees@xxxxxxxxxx>

Looks good. Thanks.

Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

> ---
> Cc: Jonathan Corbet <corbet@xxxxxxx>
> Cc: <linux-doc@xxxxxxxxxxxxxxx>
> Cc: "Matthew Wilcox (Oracle)" <willy@xxxxxxxxxxxxx>
> Cc: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx>
> Cc: Andy Shevchenko <andriy.shevchenko@xxxxxxxxxxxxxxx>
> Cc: Petr Mladek <pmladek@xxxxxxxx>
> Cc: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
> Cc: Shuah Khan <skhan@xxxxxxxxxxxxxxxxxxx>
> Cc: Steven Rostedt <rostedt@xxxxxxxxxxx>
> ---
>  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