Convert existing API doc in ptrlist.c to a kerneldoc-like
format and document a few more interfaces.
This is in preparation tu support the extraction of API
documention from the source files.
Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx>
---
ptrlist.c | 64 ++++++++++++++++++++++++++++++++++++++++++++++---------
1 file changed, 54 insertions(+), 10 deletions(-)
diff --git a/ptrlist.c b/ptrlist.c
index 8402f8d2b..6ea63ab4f 100644
--- a/ptrlist.c
+++ b/ptrlist.c
@@ -1,10 +1,13 @@
/*
* ptrlist.c
*
- * Pointer list manipulation
- *
* (C) Copyright Linus Torvalds 2003-2005
*/
+
+///
+// Pointer list manipulation
+// -------------------------
+
#include <stdlib.h>
#include <string.h>
#include <assert.h>
@@ -16,6 +19,10 @@
__DECLARE_ALLOCATOR(struct ptr_list, ptrlist);
__ALLOCATOR(struct ptr_list, "ptr list", ptrlist);
+///
+// get the size of a ptrlist
+// @head: the head of the list
+// Returns the size of the list given by @head.
int ptr_list_size(struct ptr_list *head)
{
int nr = 0;
@@ -29,13 +36,20 @@ int ptr_list_size(struct ptr_list *head)
return nr;
}
-/*
- * Linearize the entries of a list up to a total of 'max',
+/**
+ * linearize the entries of a list
+ *
+ * @head: the list to be linearized
+ * @arr: a ``void*`` array to fill with @head's entries
+ * @max: the maximum number of entries to store into @arr
+ * @return: the number of entries linearized.
+ *
+ * Linearize the entries of a list up to a total of @max,
* and return the nr of entries linearized.
*
- * The array to linearize into (second argument) should really
- * be "void *x[]", but we want to let people fill in any kind
- * of pointer array, so let's just call it "void **".
+ * The array to linearize into (@arr) should really
+ * be ``void *x[]``, but we want to let people fill in any kind
+ * of pointer array, so let's just call it ``void **``.
*/
int linearize_ptr_list(struct ptr_list *head, void **arr, int max)
{
@@ -58,7 +72,11 @@ int linearize_ptr_list(struct ptr_list *head, void **arr, int max)
return nr;
}
-/*
+/**
+ * pack a ptrlist
+ *
+ * @listp: a pointer to the list to be packed.
+ *
* When we've walked the list and deleted entries,
* we may need to re-pack it so that we don't have
* any empty blocks left (empty blocks upset the
@@ -148,6 +166,11 @@ void **__add_ptr_list(struct ptr_list **listp, void *ptr, unsigned long tag)
return ret;
}
+///
+// delete an entry from a ptrlist
+// @list: a pointer to the list
+// @entry: the item to be deleted
+// @count: the minimum number of times @entry should be deleted or 0.
int delete_ptr_list_entry(struct ptr_list **list, void *entry, int count)
{
void *ptr;
@@ -165,7 +188,14 @@ out:
return count;
}
-int replace_ptr_list_entry(struct ptr_list **list, void *old_ptr, void *new_ptr, int count)
+///
+// replace an entry in a ptrlist
+// @list: a pointer to the list
+// @old_ptr: the entry to be replaced
+// @new_ptr: the new entry
+// @count: the minimum number of times @entry should be deleted or 0.
+int replace_ptr_list_entry(struct ptr_list **list, void *old_ptr,
+ void *new_ptr, int count)
{
void *ptr;
@@ -181,7 +211,8 @@ out:
return count;
}
-/* This removes the last entry, but doesn't pack the ptr list */
+///
+// remove the last entry but doesn't pack the ptr list
void * undo_ptr_list_last(struct ptr_list **head)
{
struct ptr_list *last, *first = *head;
@@ -202,6 +233,8 @@ void * undo_ptr_list_last(struct ptr_list **head)
return NULL;
}
+///
+// remove the last entry and repack the list
void * delete_ptr_list_last(struct ptr_list **head)
{
void *ptr = NULL;
@@ -222,6 +255,11 @@ void * delete_ptr_list_last(struct ptr_list **head)
return ptr;
}
+///
+// concat two ptrlists
+// @a: the source list
+// @b: a pointer to the destination list.
+// The element of @a are added at the end of @b.
void concat_ptr_list(struct ptr_list *a, struct ptr_list **b)
{
void *entry;
@@ -230,6 +268,12 @@ void concat_ptr_list(struct ptr_list *a, struct ptr_list **b)
} END_FOR_EACH_PTR(entry);
}
+///
+// free a ptrlist
+// @listp: a pointer to the list
+// Each blocks of the list are freed.
+// @note: the list entries are not freed.
+// @extra-tag: something odd with the doc here
void __free_ptr_list(struct ptr_list **listp)
{
struct ptr_list *tmp, *list = *listp;
--
2.17.0
--
To unsubscribe from this list: send the line "unsubscribe linux-sparse" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
