[PATCH 0/3] Generate documentation for error pointer functions

[PATCH 0/3] Generate documentation for error pointer functions

[James Seo]

The error pointer functions are collectively mentioned hundreds of times
in existing documentation (e.g. "Return: an ERR_PTR() on failure.",
"If IS_ERR() is true, the function failed and PTR_ERR() gives you the
error code.")

This series adds kerneldocs for them and brings them into the docs build,
immediately turning most such mentions into automatic cross-references.

James Seo (3):
  Documentation: conf.py: Add __force to c_id_attributes
  err.h: Add missing kerneldocs for error pointer functions
  Documentation: core-api: Add error pointer functions to kernel-api

 Documentation/conf.py                 |  1 +
 Documentation/core-api/kernel-api.rst |  6 ++++
 include/linux/err.h                   | 48 +++++++++++++++++++++++++++
 3 files changed, 55 insertions(+)

-- 
2.34.1

[PATCH 1/3] Documentation: conf.py: Add __force to c_id_attributes

[James Seo]

Fixes the following error in the docs build that occurs with recent
versions of Sphinx when parsing kerneldocs for a function with the
'__force' macro in its signature:

  ./include/linux/err.h:51: WARNING: Error in declarator or parameters
  Error in declarator or parameters
  Invalid C declaration: Expected identifier, got keyword: void [error at 35]
    void * ERR_CAST (__force const void *ptr)
    -----------------------------------^

Currently, almost all of the few in-signature occurrences of '__force'
are in the error pointer functions. Of those, ERR_CAST() is the only
one with kerneldocs, but the kerneldocs aren't even being used to
generate documentation. This change will allow all the error pointer
functions to be properly documented.

In addition to '__force', <linux/compiler_types.h> also defines
'__nocast', '__safe', and '__private'. These are not currently used in
any function signatures and do not need to be added to the docs config.

Signed-off-by: James Seo <james@equiv.tech>
---
 Documentation/conf.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 37314afd1ac8..d4fdf6a3875a 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -74,6 +74,7 @@ if major >= 3:
             "__percpu",
             "__rcu",
             "__user",
+            "__force",
 
             # include/linux/compiler_attributes.h:
             "__alias",
-- 
2.34.1

[PATCH 2/3] err.h: Add missing kerneldocs for error pointer functions

[James Seo]

Add kerneldocs for ERR_PTR(), PTR_ERR(), PTR_ERR_OR_ZERO(), IS_ERR(),
and IS_ERR_OR_NULL(). Doing so will help convert hundreds of mentions
of them in existing documentation into automatic cross-references.

Also add kerneldocs for IS_ERR_VALUE(). Doing so adds no automatic
cross-references, but this macro has a slightly different use case
than the functionally similar IS_ERR(), and documenting it may be
helpful to readers who encounter it in existing code.

ERR_CAST() already has kerneldocs and has not been touched.

Signed-off-by: James Seo <james@equiv.tech>
---
 include/linux/err.h | 48 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/include/linux/err.h b/include/linux/err.h
index a139c64aef2a..c804118ae73d 100644
--- a/include/linux/err.h
+++ b/include/linux/err.h
@@ -19,23 +19,54 @@
 
 #ifndef __ASSEMBLY__
 
+/**
+ * IS_ERR_VALUE - Detect an error pointer.
+ * @x: The pointer to check.
+ *
+ * Like IS_ERR(), but does not generate a compiler warning if result is unused.
+ */
 #define IS_ERR_VALUE(x) unlikely((unsigned long)(void *)(x) >= (unsigned long)-MAX_ERRNO)
 
+/**
+ * ERR_PTR - Create an error pointer.
+ * @error: A negative error code.
+ *
+ * Encodes @error into a pointer value. Users should consider the result
+ * opaque and not assume anything about how the error is encoded.
+ *
+ * Return: A pointer with @error encoded within its value.
+ */
 static inline void * __must_check ERR_PTR(long error)
 {
 	return (void *) error;
 }
 
+/**
+ * PTR_ERR - Extract the error code from an error pointer.
+ * @ptr: An error pointer.
+ * Return: The error code within @ptr.
+ */
 static inline long __must_check PTR_ERR(__force const void *ptr)
 {
 	return (long) ptr;
 }
 
+/**
+ * IS_ERR - Detect an error pointer.
+ * @ptr: The pointer to check.
+ * Return: true if @ptr is an error pointer, false otherwise.
+ */
 static inline bool __must_check IS_ERR(__force const void *ptr)
 {
 	return IS_ERR_VALUE((unsigned long)ptr);
 }
 
+/**
+ * IS_ERR_OR_NULL - Detect an error pointer or a null pointer.
+ * @ptr: The pointer to check.
+ *
+ * Like IS_ERR(), but also returns true for a null pointer.
+ */
 static inline bool __must_check IS_ERR_OR_NULL(__force const void *ptr)
 {
 	return unlikely(!ptr) || IS_ERR_VALUE((unsigned long)ptr);
@@ -54,6 +85,23 @@ static inline void * __must_check ERR_CAST(__force const void *ptr)
 	return (void *) ptr;
 }
 
+/**
+ * PTR_ERR_OR_ZERO - Extract the error code from a pointer if it has one.
+ * @ptr: A potential error pointer.
+ *
+ * Convenience function that can be used inside a function that returns
+ * an error code to propagate errors received as error pointers.
+ * For example, ``return PTR_ERR_OR_ZERO(ptr);`` replaces:
+ *
+ * .. code-block:: c
+ *
+ *	if (IS_ERR(ptr))
+ *		return PTR_ERR(ptr);
+ *	else
+ *		return 0;
+ *
+ * Return: The error code within @ptr if it is an error pointer; 0 otherwise.
+ */
 static inline int __must_check PTR_ERR_OR_ZERO(__force const void *ptr)
 {
 	if (IS_ERR(ptr))
-- 
2.34.1

[PATCH 3/3] Documentation: core-api: Add error pointer functions to kernel-api

[James Seo]

Bring the error pointer functions (e.g. ERR_PTR(), PTR_ERR()) into
the docs build so that they can be cross-referenced elsewhere.

List them as kernel library functions in the kernel-api document.
Nowhere else seems to fit, and they need to go *somewhere*.

Signed-off-by: James Seo <james@equiv.tech>
---
 Documentation/core-api/kernel-api.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 9b3f3e5f5a95..44b96e18f8f2 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -96,6 +96,12 @@ Command-line Parsing
 .. kernel-doc:: lib/cmdline.c
    :export:
 
+Error Pointers
+--------------
+
+.. kernel-doc:: include/linux/err.h
+   :internal:
+
 Sorting
 -------
 
-- 
2.34.1

Re: [PATCH 0/3] Generate documentation for error pointer functions

[Jonathan Corbet]

James Seo <james@equiv.tech> writes:

> The error pointer functions are collectively mentioned hundreds of times
> in existing documentation (e.g. "Return: an ERR_PTR() on failure.",
> "If IS_ERR() is true, the function failed and PTR_ERR() gives you the
> error code.")
>
> This series adds kerneldocs for them and brings them into the docs build,
> immediately turning most such mentions into automatic cross-references.
>
> James Seo (3):
>   Documentation: conf.py: Add __force to c_id_attributes
>   err.h: Add missing kerneldocs for error pointer functions
>   Documentation: core-api: Add error pointer functions to kernel-api
>
>  Documentation/conf.py                 |  1 +
>  Documentation/core-api/kernel-api.rst |  6 ++++
>  include/linux/err.h                   | 48 +++++++++++++++++++++++++++
>  3 files changed, 55 insertions(+)

Series applied, thanks.

jon