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

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

[Kees Cook]

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@google.com>
Signed-off-by: Bill Wendling <morbo@google.com>
Signed-off-by: Kees Cook <kees@kernel.org>
---
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: <linux-doc@vger.kernel.org>
Cc: "Matthew Wilcox (Oracle)" <willy@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Cc: Petr Mladek <pmladek@suse.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Shuah Khan <skhan@linuxfoundation.org>
Cc: Steven Rostedt <rostedt@goodmis.org>
---
 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.
  */
-- 
2.34.1

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@google.com>
> Signed-off-by: Bill Wendling <morbo@google.com>
> Signed-off-by: Kees Cook <kees@kernel.org>

Looks good. Thanks.

Tested-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

> ---
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: <linux-doc@vger.kernel.org>
> Cc: "Matthew Wilcox (Oracle)" <willy@infradead.org>
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
> Cc: Petr Mladek <pmladek@suse.com>
> Cc: Randy Dunlap <rdunlap@infradead.org>
> Cc: Shuah Khan <skhan@linuxfoundation.org>
> Cc: Steven Rostedt <rostedt@goodmis.org>
> ---
>  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