On Mon, 14 May 2018, Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx> wrote:
> Convert existing API doc in ptrlist.c to a kerneldoc-like
> format and document a few more interfaces.
It's your code base, I don't have a vested interest, but since you Cc'd
me I can't help but urge you to consider choosing *one* documentation
comment style, and sticking with it. That is, either /** ... */ or ///
but not both.
In the same vein, I suggest sticking with minimalistic mainstream
documentation comment syntaxes. Steal the best parts of
javadoc/doxygen/kernel-doc, but don't emulate their mistakes. ;)
BR,
Jani.
>
> 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;
--
Jani Nikula, Intel Open Source Technology Center
--
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
