linux-kernel - [PATCH] Generic radix tree: add kernel-doc chapter

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <f02c9f2a-ca10-4485-e747-89d003a50ab2@infradead.org>
Date:   Mon, 10 Sep 2018 16:18:42 -0700
From:   Randy Dunlap <rdunlap@...radead.org>
To:     Kent Overstreet <kent.overstreet@...il.com>,
        linux-kernel@...r.kernel.org
Cc:     Dave Hansen <dave.hansen@...el.com>,
        Matthew Wilcox <willy@...radead.org>,
        "linux-doc@...r.kernel.org" <linux-doc@...r.kernel.org>
Subject: [PATCH] Generic radix tree: add kernel-doc chapter

From: Randy Dunlap <rdunlap@...radead.org>

Add a generic-radix-tree chapter to core-api kernel documentation.

Also fix a few kernel-doc warnings for misssing function (or macro)
parameters:

../include/linux/generic-radix-tree.h:93: warning: Function parameter or member '_radix' not described in 'genradix_free'
../include/linux/generic-radix-tree.h:161: warning: Function parameter or member '_idx' not described in 'genradix_iter_init'

Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
Cc: Kent Overstreet <kent.overstreet@...il.com>
Cc: Matthew Wilcox <willy@...radead.org>
Cc: Dave Hansen <dave.hansen@...el.com>
Cc: linux-doc@...r.kernel.org
---
 Documentation/core-api/generic-radix-tree.rst |   13 +++++++++++++
 Documentation/core-api/index.rst              |    1 +
 include/linux/generic-radix-tree.h            |   12 ++++++++----
 3 files changed, 22 insertions(+), 4 deletions(-)

--- /dev/null
+++ linux-next-20180910/Documentation/core-api/generic-radix-tree.rst
@@ -0,0 +1,13 @@
+
+=================================
+Generic radix trees/sparse arrays
+=================================
+
+.. kernel-doc:: include/linux/generic-radix-tree.h
+   :doc: Generic radix trees/sparse arrays
+
+generic radix tree functions
+----------------------------
+
+.. kernel-doc:: include/linux/generic-radix-tree.h
+   :functions:
--- linux-next-20180910.orig/Documentation/core-api/index.rst
+++ linux-next-20180910/Documentation/core-api/index.rst
@@ -27,6 +27,7 @@ Core utilities
    errseq
    printk-formats
    circular-buffers
+   generic-radix-tree
    mm-api
    gfp_mask-from-fs-io
    timekeeping
--- linux-next-20180910.orig/include/linux/generic-radix-tree.h
+++ linux-next-20180910/include/linux/generic-radix-tree.h
@@ -1,16 +1,18 @@
 #ifndef _LINUX_GENERIC_RADIX_TREE_H
 #define _LINUX_GENERIC_RADIX_TREE_H
 
-/*
- * Generic radix trees/sparse arrays:
+/**
+ * DOC: Generic radix trees/sparse arrays
  *
  * Very simple and minimalistic, supporting arbitrary size entries up to
  * PAGE_SIZE.
  *
  * A genradix is defined with the type it will store, like so:
+ *
  * static GENRADIX(struct foo) foo_genradix;
  *
  * The main operations are:
+ *
  * - genradix_init(radix) - initialize an empty genradix
  *
  * - genradix_free(radix) - free all memory owned by the genradix and
@@ -86,6 +88,7 @@ void __genradix_free(struct __genradix *
 
 /**
  * genradix_free: free all memory owned by a genradix
+ * @_radix: the genradix to free
  *
  * After freeing, @_radix will be reinitialized and empty
  */
@@ -130,7 +133,8 @@ void *__genradix_ptr(struct __genradix *
 void *__genradix_ptr_alloc(struct __genradix *, size_t, gfp_t);
 
 /**
- * genradix_ptr - get a pointer to a genradix entry, allocating it if necessary
+ * genradix_ptr_alloc - get a pointer to a genradix entry, allocating it
+ *			if necessary
  * @_radix:	genradix to access
  * @_idx:	index to fetch
  * @_gfp:	gfp mask
@@ -151,7 +155,7 @@ struct genradix_iter {
 /**
  * genradix_iter_init - initialize a genradix_iter
  * @_radix:	genradix that will be iterated over
- * @_idx	index to start iterating from
+ * @_idx:	index to start iterating from
  */
 #define genradix_iter_init(_radix, _idx)			\
 	((struct genradix_iter) {				\