[PATCH v2 net-next 7/7] socket: Clean up kdoc for sock_create() and sock_create_lite().

Kuniyuki Iwashima
2025-05-23T18:24:48Z

__sock_create() is now static and the same doc exists on sock_create()
and sock_create_kern().

Also, __sock_create() says "On failure @res is set to %NULL.", but
this is always false.

In addition, the old style kdoc is a bit corrupted and we can't see the
DESCRIPTION section:

$ scripts/kernel-doc -man net/socket.c | scripts/split-man.pl /tmp/man
$ man /tmp/man/sock_create.9

Let's clean them up.

Signed-off-by: Kuniyuki Iwashima <kuniyu@amazon.com>
---
net/socket.c | 58 ++++++++++++++++++++++------------------------------
1 file changed, 25 insertions(+), 33 deletions(-)

diff --git a/net/socket.c b/net/socket.c
index 9ad352183fae..e4e9f5cc5d70 100644
--- a/net/socket.c
+++ b/net/socket.c
@@ -1315,18 +1315,20 @@ static long sock_ioctl(struct file *file, unsigned cmd, unsigned long arg)
}

/**
- * sock_create_lite - creates a socket
- * @family: protocol family (AF_INET, ...)
- * @type: communication type (SOCK_STREAM, ...)
- * @protocol: protocol (0, ...)
- * @res: new socket
+ * sock_create_lite - creates a socket
*
- * Creates a new socket and assigns it to @res, passing through LSM.
- * The new socket initialization is not complete, see kernel_accept().
- * Returns 0 or an error. On failure @res is set to %NULL.
- * This function internally uses GFP_KERNEL.
+ * @family: protocol family (AF_INET, ...)
+ * @type: communication type (SOCK_STREAM, ...)
+ * @protocol: protocol (0, ...)
+ * @res: new socket
+ *
+ * Creates a new socket and assigns it to @res, passing through LSM.
+ *
+ * The new socket initialization is not complete, see kernel_accept().
+ *
+ * Context: Process context. This function internally uses GFP_KERNEL.
+ * Return: 0 or an error. On failure @res is set to %NULL.
*/
-
int sock_create_lite(int family, int type, int protocol, struct socket **res)
{
int err;
@@ -1452,21 +1454,6 @@ int sock_wake_async(struct socket_wq *wq, int how, int band)
}
EXPORT_SYMBOL(sock_wake_async);

-/**
- * __sock_create - creates a socket
- * @net: net namespace
- * @family: protocol family (AF_INET, ...)
- * @type: communication type (SOCK_STREAM, ...)
- * @protocol: protocol (0, ...)
- * @res: new socket
- * @kern: boolean for kernel space sockets
- *
- * Creates a new socket and assigns it to @res, passing through LSM.
- * Returns 0 or an error. On failure @res is set to %NULL. @kern must
- * be set to true if the socket resides in kernel space.
- * This function internally uses GFP_KERNEL.
- */
-
static int __sock_create(struct net *net, int family, int type, int protocol,
struct socket **res, int kern)
{
@@ -1583,16 +1570,21 @@ static int __sock_create(struct net *net, int family, int type, int protocol,
}

/**
- * sock_create - creates a socket
- * @family: protocol family (AF_INET, ...)
- * @type: communication type (SOCK_STREAM, ...)
- * @protocol: protocol (0, ...)
- * @res: new socket
+ * sock_create - creates a socket for userspace
+ *
+ * @family: protocol family (AF_INET, ...)
+ * @type: communication type (SOCK_STREAM, ...)
+ * @protocol: protocol (0, ...)
+ * @res: new socket
*
- * A wrapper around __sock_create().
- * Returns 0 or an error. This function internally uses GFP_KERNEL.
+ * Creates a new socket and assigns it to @res, passing through LSM.
+ *
+ * The socket is for userspace and should be exposed via a file
+ * descriptor and BPF hooks (see inet_create(), inet_release(), etc).
+ *
+ * Context: Process context. This function internally uses GFP_KERNEL.
+ * Return: 0 or an error.
*/
-
int sock_create(int family, int type, int protocol, struct socket **res)
{
return __sock_create(current->nsproxy->net_ns, family, type, protocol, res, 0);
--
2.49.0