openocd: fix incorrect doxygen comments

Use '@param' in front of function's parameters and '@a' when the
parameter is recalled in the description.

This fixes doxygen complains:
	warning: Found unknown command '@buff16'

While there, fix a minor typo s/occured/occurred/ in a comment and
the typo s/@apram/@param/ in a doxygen comment.

Change-Id: I5cd86a80adef552331310a21c55ec5d11354be21
Signed-off-by: Antonio Borneo <borneo.antonio@gmail.com>
Reviewed-on: http://openocd.zylin.com/6001
Tested-by: jenkins

1 files changed, 106 insertions, 106 deletions

diff --git a/src/helper/list.h b/src/helper/list.h
index 6fd0e7c..7f60464 100644
--- a/src/helper/list.h
+++ b/src/helper/list.h
@@ -64,8 +64,8 @@ extern void __list_add(struct list_head *new,
 
 /**
  * list_add - add a new entry
- * @new: new entry to be added
- * @head: list head to add it after
+ * @param new new entry to be added
+ * @param head list head to add it after
  *
  * Insert a new entry after the specified head.
  * This is good for implementing stacks.
@@ -78,8 +78,8 @@ static inline void list_add(struct list_head *new, struct list_head *head)
 
 /**
  * list_add_tail - add a new entry
- * @new: new entry to be added
- * @head: list head to add it before
+ * @param new new entry to be added
+ * @param head list head to add it before
  *
  * Insert a new entry before the specified head.
  * This is useful for implementing queues.
@@ -104,7 +104,7 @@ static inline void __list_del(struct list_head *prev, struct list_head *next)
 
 /**
  * list_del - deletes entry from list.
- * @entry: the element to delete from the list.
+ * @param entry the element to delete from the list.
  * Note: list_empty() on entry does not return true after this, the entry is
  * in an undefined state.
  */
@@ -127,10 +127,10 @@ extern void list_del(struct list_head *entry);
 
 /**
  * list_replace - replace old entry by new one
- * @old : the element to be replaced
- * @new : the new element to insert
+ * @param old the element to be replaced
+ * @param new the new element to insert
  *
- * If @old was empty, it will be overwritten.
+ * If @a old was empty, it will be overwritten.
  */
 static inline void list_replace(struct list_head *old,
 	struct list_head *new)
@@ -150,7 +150,7 @@ static inline void list_replace_init(struct list_head *old,
 
 /**
  * list_del_init - deletes entry from list and reinitialize it.
- * @entry: the element to delete from the list.
+ * @param entry the element to delete from the list.
  */
 static inline void list_del_init(struct list_head *entry)
 {
@@ -160,8 +160,8 @@ static inline void list_del_init(struct list_head *entry)
 
 /**
  * list_move - delete from one list and add as another's head
- * @list: the entry to move
- * @head: the head that will precede our entry
+ * @param list the entry to move
+ * @param head the head that will precede our entry
  */
 static inline void list_move(struct list_head *list, struct list_head *head)
 {
@@ -171,8 +171,8 @@ static inline void list_move(struct list_head *list, struct list_head *head)
 
 /**
  * list_move_tail - delete from one list and add as another's tail
- * @list: the entry to move
- * @head: the head that will follow our entry
+ * @param list the entry to move
+ * @param head the head that will follow our entry
  */
 static inline void list_move_tail(struct list_head *list,
 	struct list_head *head)
@@ -182,9 +182,9 @@ static inline void list_move_tail(struct list_head *list,
 }
 
 /**
- * list_is_last - tests whether @list is the last entry in list @head
- * @list: the entry to test
- * @head: the head of the list
+ * list_is_last - tests whether @a list is the last entry in list @a head
+ * @param list the entry to test
+ * @param head the head of the list
  */
 static inline int list_is_last(const struct list_head *list,
 	const struct list_head *head)
@@ -194,7 +194,7 @@ static inline int list_is_last(const struct list_head *list,
 
 /**
  * list_empty - tests whether a list is empty
- * @head: the list to test.
+ * @param head the list to test.
  */
 static inline int list_empty(const struct list_head *head)
 {
@@ -203,7 +203,7 @@ static inline int list_empty(const struct list_head *head)
 
 /**
  * list_empty_careful - tests whether a list is empty and not being modified
- * @head: the list to test
+ * @param head the list to test
  *
  * Description:
  * tests whether a list is empty _and_ checks that no other CPU might be
@@ -222,7 +222,7 @@ static inline int list_empty_careful(const struct list_head *head)
 
 /**
  * list_rotate_left - rotate the list to the left
- * @head: the head of the list
+ * @param head the head of the list
  */
 static inline void list_rotate_left(struct list_head *head)
 {
@@ -236,7 +236,7 @@ static inline void list_rotate_left(struct list_head *head)
 
 /**
  * list_is_singular - tests whether a list has just one entry.
- * @head: the list to test.
+ * @param head the list to test.
  */
 static inline int list_is_singular(const struct list_head *head)
 {
@@ -257,14 +257,14 @@ static inline void __list_cut_position(struct list_head *list,
 
 /**
  * list_cut_position - cut a list into two
- * @list: a new list to add all removed entries
- * @head: a list with entries
- * @entry: an entry within head, could be the head itself
+ * @param list a new list to add all removed entries
+ * @param head a list with entries
+ * @param entry an entry within head, could be the head itself
  *	and if so we won't cut the list
  *
- * This helper moves the initial part of @head, up to and
- * including @entry, from @head to @list. You should
- * pass on @entry an element you know is on @head. @list
+ * This helper moves the initial part of @a head, up to and
+ * including @a entry, from @a head to @a list. You should
+ * pass on @a entry an element you know is on @a head. @a list
  * should be an empty list or a list you do not care about
  * losing its data.
  *
@@ -299,8 +299,8 @@ static inline void __list_splice(const struct list_head *list,
 
 /**
  * list_splice - join two lists, this is designed for stacks
- * @list: the new list to add.
- * @head: the place to add it in the first list.
+ * @param list the new list to add.
+ * @param head the place to add it in the first list.
  */
 static inline void list_splice(const struct list_head *list,
 	struct list_head *head)
@@ -311,8 +311,8 @@ static inline void list_splice(const struct list_head *list,
 
 /**
  * list_splice_tail - join two lists, each list being a queue
- * @list: the new list to add.
- * @head: the place to add it in the first list.
+ * @param list the new list to add.
+ * @param head the place to add it in the first list.
  */
 static inline void list_splice_tail(struct list_head *list,
 	struct list_head *head)
@@ -323,10 +323,10 @@ static inline void list_splice_tail(struct list_head *list,
 
 /**
  * list_splice_init - join two lists and reinitialise the emptied list.
- * @list: the new list to add.
- * @head: the place to add it in the first list.
+ * @param list the new list to add.
+ * @param head the place to add it in the first list.
  *
- * The list at @list is reinitialised
+ * The list at @a list is reinitialised
  */
 static inline void list_splice_init(struct list_head *list,
 	struct list_head *head)
@@ -339,11 +339,11 @@ static inline void list_splice_init(struct list_head *list,
 
 /**
  * list_splice_tail_init - join two lists and reinitialise the emptied list
- * @list: the new list to add.
- * @head: the place to add it in the first list.
+ * @param list the new list to add.
+ * @param head the place to add it in the first list.
  *
  * Each of the lists is a queue.
- * The list at @list is reinitialised
+ * The list at @a list is reinitialised
  */
 static inline void list_splice_tail_init(struct list_head *list,
 	struct list_head *head)
@@ -356,18 +356,18 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_entry - get the struct for this entry
- * @ptr:	the &struct list_head pointer.
- * @type:	the type of the struct this is embedded in.
- * @member:	the name of the list_struct within the struct.
+ * @param ptr    the &struct list_head pointer.
+ * @param type   the type of the struct this is embedded in.
+ * @param member the name of the list_struct within the struct.
  */
 #define list_entry(ptr, type, member) \
 	container_of(ptr, type, member)
 
 /**
  * list_first_entry - get the first element from a list
- * @ptr:	the list head to take the element from.
- * @type:	the type of the struct this is embedded in.
- * @member:	the name of the list_struct within the struct.
+ * @param ptr    the list head to take the element from.
+ * @param type   the type of the struct this is embedded in.
+ * @param member the name of the list_struct within the struct.
  *
  * Note, that list is expected to be not empty.
  */
@@ -376,8 +376,8 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each	-	iterate over a list
- * @pos:	the &struct list_head to use as a loop cursor.
- * @head:	the head for your list.
+ * @param pos  the &struct list_head to use as a loop cursor.
+ * @param head the head for your list.
  */
 #define list_for_each(pos, head) \
 	for (pos = (head)->next; prefetch(pos->next), pos != (head); \
@@ -385,8 +385,8 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * __list_for_each	-	iterate over a list
- * @pos:	the &struct list_head to use as a loop cursor.
- * @head:	the head for your list.
+ * @param pos  the &struct list_head to use as a loop cursor.
+ * @param head the head for your list.
  *
  * This variant differs from list_for_each() in that it's the
  * simplest possible list iteration code, no prefetching is done.
@@ -398,8 +398,8 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_prev	-	iterate over a list backwards
- * @pos:	the &struct list_head to use as a loop cursor.
- * @head:	the head for your list.
+ * @param pos  the &struct list_head to use as a loop cursor.
+ * @param head the head for your list.
  */
 #define list_for_each_prev(pos, head) \
 	for (pos = (head)->prev; prefetch(pos->prev), pos != (head); \
@@ -407,9 +407,9 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_safe - iterate over a list safe against removal of list entry
- * @pos:	the &struct list_head to use as a loop cursor.
- * @n:		another &struct list_head to use as temporary storage
- * @head:	the head for your list.
+ * @param pos  the &struct list_head to use as a loop cursor.
+ * @param n    another &struct list_head to use as temporary storage
+ * @param head the head for your list.
  */
 #define list_for_each_safe(pos, n, head) \
 	for (pos = (head)->next, n = pos->next; pos != (head); \
@@ -417,9 +417,9 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_prev_safe - iterate over a list backwards safe against removal of list entry
- * @pos:	the &struct list_head to use as a loop cursor.
- * @n:		another &struct list_head to use as temporary storage
- * @head:	the head for your list.
+ * @param pos  the &struct list_head to use as a loop cursor.
+ * @param n    another &struct list_head to use as temporary storage
+ * @param head the head for your list.
  */
 #define list_for_each_prev_safe(pos, n, head) \
 	for (pos = (head)->prev, n = pos->prev;	\
@@ -428,9 +428,9 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_entry	-	iterate over list of given type
- * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the type * to use as a loop cursor.
+ * @param head   the head for your list.
+ * @param member the name of the list_struct within the struct.
  */
 #define list_for_each_entry(pos, head, member)				\
 	for (pos = list_entry((head)->next, typeof(*pos), member);	\
@@ -439,9 +439,9 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_entry_reverse - iterate backwards over list of given type.
- * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the type * to use as a loop cursor.
+ * @param head   the head for your list.
+ * @param member the name of the list_struct within the struct.
  */
 #define list_for_each_entry_reverse(pos, head, member)			\
 	for (pos = list_entry((head)->prev, typeof(*pos), member);	\
@@ -450,9 +450,9 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_prepare_entry - prepare a pos entry for use in list_for_each_entry_continue()
- * @pos:	the type * to use as a start point
- * @head:	the head of the list
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the type * to use as a start point
+ * @param head   the head of the list
+ * @param member the name of the list_struct within the struct.
  *
  * Prepares a pos entry for use as a start point in list_for_each_entry_continue().
  */
@@ -461,9 +461,9 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_entry_continue - continue iteration over list of given type
- * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the type * to use as a loop cursor.
+ * @param head   the head for your list.
+ * @param member the name of the list_struct within the struct.
  *
  * Continue to iterate over list of given type, continuing after
  * the current position.
@@ -475,9 +475,9 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_entry_continue_reverse - iterate backwards from the given point
- * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the type * to use as a loop cursor.
+ * @param head   the head for your list.
+ * @param member the name of the list_struct within the struct.
  *
  * Start to iterate over list of given type backwards, continuing after
  * the current position.
@@ -489,9 +489,9 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_entry_from - iterate over list of given type from the current point
- * @pos:	the type * to use as a loop cursor.
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the type * to use as a loop cursor.
+ * @param head   the head for your list.
+ * @param member the name of the list_struct within the struct.
  *
  * Iterate over list of given type, continuing from current position.
  */
@@ -501,10 +501,10 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_entry_safe - iterate over list of given type safe against removal of list entry
- * @pos:	the type * to use as a loop cursor.
- * @n:		another type * to use as temporary storage
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the type * to use as a loop cursor.
+ * @param n      another type * to use as temporary storage
+ * @param head   the head for your list.
+ * @param member the name of the list_struct within the struct.
  */
 #define list_for_each_entry_safe(pos, n, head, member)			\
 	for (pos = list_entry((head)->next, typeof(*pos), member),	\
@@ -514,10 +514,10 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_entry_safe_continue - continue list iteration safe against removal
- * @pos:	the type * to use as a loop cursor.
- * @n:		another type * to use as temporary storage
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the type * to use as a loop cursor.
+ * @param n      another type * to use as temporary storage
+ * @param head   the head for your list.
+ * @param member the name of the list_struct within the struct.
  *
  * Iterate over list of given type, continuing after current point,
  * safe against removal of list entry.
@@ -530,10 +530,10 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_entry_safe_from - iterate over list from current point safe against removal
- * @pos:	the type * to use as a loop cursor.
- * @n:		another type * to use as temporary storage
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the type * to use as a loop cursor.
+ * @param n      another type * to use as temporary storage
+ * @param head   the head for your list.
+ * @param member the name of the list_struct within the struct.
  *
  * Iterate over list of given type from current point, safe against
  * removal of list entry.
@@ -545,10 +545,10 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_for_each_entry_safe_reverse - iterate backwards over list safe against removal
- * @pos:	the type * to use as a loop cursor.
- * @n:		another type * to use as temporary storage
- * @head:	the head for your list.
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the type * to use as a loop cursor.
+ * @param n      another type * to use as temporary storage
+ * @param head   the head for your list.
+ * @param member the name of the list_struct within the struct.
  *
  * Iterate backwards over list of given type, safe against removal
  * of list entry.
@@ -561,9 +561,9 @@ static inline void list_splice_tail_init(struct list_head *list,
 
 /**
  * list_safe_reset_next - reset a stale list_for_each_entry_safe loop
- * @pos:	the loop cursor used in the list_for_each_entry_safe loop
- * @n:		temporary storage used in list_for_each_entry_safe
- * @member:	the name of the list_struct within the struct.
+ * @param pos    the loop cursor used in the list_for_each_entry_safe loop
+ * @param n      temporary storage used in list_for_each_entry_safe
+ * @param member the name of the list_struct within the struct.
  *
  * list_safe_reset_next is not safe to use in general if the list may be
  * modified concurrently (eg. the lock is dropped in the loop body). An
@@ -686,10 +686,10 @@ static inline void hlist_move_list(struct hlist_head *old,
 
 /**
  * hlist_for_each_entry	- iterate over list of given type
- * @tpos:	the type * to use as a loop cursor.
- * @pos:	the &struct hlist_node to use as a loop cursor.
- * @head:	the head for your list.
- * @member:	the name of the hlist_node within the struct.
+ * @param tpos   the type * to use as a loop cursor.
+ * @param pos    the &struct hlist_node to use as a loop cursor.
+ * @param head   the head for your list.
+ * @param member the name of the hlist_node within the struct.
  */
 #define hlist_for_each_entry(tpos, pos, head, member)			 \
 	for (pos = (head)->first;					 \
@@ -699,9 +699,9 @@ static inline void hlist_move_list(struct hlist_head *old,
 
 /**
  * hlist_for_each_entry_continue - iterate over a hlist continuing after current point
- * @tpos:	the type * to use as a loop cursor.
- * @pos:	the &struct hlist_node to use as a loop cursor.
- * @member:	the name of the hlist_node within the struct.
+ * @param tpos   the type * to use as a loop cursor.
+ * @param pos    the &struct hlist_node to use as a loop cursor.
+ * @param member the name of the hlist_node within the struct.
  */
 #define hlist_for_each_entry_continue(tpos, pos, member)		 \
 	for (pos = (pos)->next;						 \
@@ -711,9 +711,9 @@ static inline void hlist_move_list(struct hlist_head *old,
 
 /**
  * hlist_for_each_entry_from - iterate over a hlist continuing from current point
- * @tpos:	the type * to use as a loop cursor.
- * @pos:	the &struct hlist_node to use as a loop cursor.
- * @member:	the name of the hlist_node within the struct.
+ * @param tpos   the type * to use as a loop cursor.
+ * @param pos    the &struct hlist_node to use as a loop cursor.
+ * @param member the name of the hlist_node within the struct.
  */
 #define hlist_for_each_entry_from(tpos, pos, member)			 \
 	for (; pos && ({ prefetch(pos->next); 1; }) &&			 \
@@ -722,11 +722,11 @@ static inline void hlist_move_list(struct hlist_head *old,
 
 /**
  * hlist_for_each_entry_safe - iterate over list of given type safe against removal of list entry
- * @tpos:	the type * to use as a loop cursor.
- * @pos:	the &struct hlist_node to use as a loop cursor.
- * @n:		another &struct hlist_node to use as temporary storage
- * @head:	the head for your list.
- * @member:	the name of the hlist_node within the struct.
+ * @param tpos   the type * to use as a loop cursor.
+ * @param pos    the &struct hlist_node to use as a loop cursor.
+ * @param n      another &struct hlist_node to use as temporary storage
+ * @param head   the head for your list.
+ * @param member the name of the hlist_node within the struct.
  */
 #define hlist_for_each_entry_safe(tpos, pos, n, head, member)		 \
 	for (pos = (head)->first;					 \