idr: Add documentation

Move the idr kernel-doc to its own idr.rst file and add a few
paragraphs about how to use it.  Also add some more kernel-doc.

Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>

1 files changed, 15 insertions, 1 deletions

diff --git a/include/linux/idr.h b/include/linux/idr.h
index 86b38df6e121..7d6a6313f0ab 100644
--- a/include/linux/idr.h
+++ b/include/linux/idr.h
@@ -36,7 +36,6 @@ struct idr {
 	.idr_base = (base),						\
 	.idr_next = 0,							\
 }
-#define DEFINE_IDR(name)	struct idr name = IDR_INIT
 
 /**
  * IDR_INIT() - Initialise an IDR.
@@ -46,6 +45,15 @@ struct idr {
 #define IDR_INIT	IDR_INIT_BASE(0)
 
 /**
+ * DEFINE_IDR() - Define a statically-allocated IDR
+ * @name: Name of IDR
+ *
+ * An IDR defined using this macro is ready for use with no additional
+ * initialisation required.  It contains no IDs.
+ */
+#define DEFINE_IDR(name)	struct idr name = IDR_INIT
+
+/**
  * idr_get_cursor - Return the current position of the cyclic allocator
  * @idr: idr handle
  *
@@ -130,6 +138,12 @@ static inline void idr_init(struct idr *idr)
 	idr_init_base(idr, 0);
 }
 
+/**
+ * idr_is_empty() - Are there any IDs allocated?
+ * @idr: IDR handle.
+ *
+ * Return: %true if any IDs have been allocated from this IDR.
+ */
 static inline bool idr_is_empty(const struct idr *idr)
 {
 	return radix_tree_empty(&idr->idr_rt) &&