From 03f5a8d7b13818def1462143c034e2f7bb3f5e3c Mon Sep 17 00:00:00 2001 From: bert Date: Sun, 24 Jul 2016 12:17:18 +0200 Subject: [PATCH] gcode/lists.h: Converted plain comments into doxygen comments. Signed-off-by: bert --- src/hid/gcode/lists.h | 247 ++++++++++++++++++++++++++++++++++---------------- 1 file changed, 167 insertions(+), 80 deletions(-) diff --git a/src/hid/gcode/lists.h b/src/hid/gcode/lists.h index 60d42e6881..414c728305 100644 --- a/src/hid/gcode/lists.h +++ b/src/hid/gcode/lists.h @@ -1,84 +1,117 @@ -/* Copyright (C) 2001-2007 Peter Selinger. - This file is part of Potrace. It is free software and it is covered - by the GNU General Public License. See the file COPYING for details. */ +/*! + * \file src/hid/gcode/lists.h + * + * \brief Here we define some general list macros. + * + * Because they are macros, they should work on any datatype with a + * "->next" component. Some of them use a "hook". If elt and list are of + * type t* then hook is of type t**. A hook stands for an insertion + * point in the list, i.e., either before the first element, or between + * two elements, or after the last element. If an operation "sets the + * hook" for an element, then the hook is set to just before the + * element. One can insert something at a hook. One can also unlink at a + * hook: this means, unlink the element just after the hook. By + * "to unlink", we mean the element is removed from the list, but not + * deleted. Thus, it and its components still need to be freed. + * + * \note These macros are somewhat experimental. Only the ones that + * are actually *used* have been tested. So be careful to test any + * that you use. Looking at the output of the preprocessor, "gcc -E" + * (possibly piped though "indent"), might help too. Also: these + * macros define some internal (local) variables that start with + * "_". + * + *
+ * + *

Copyright.

\n + * + * PCB, interactive printed circuit board design + * + * Copyright (C) 2001-2007 Peter Selinger. + * + * This file is part of Potrace. It is free software and it is covered + * by the GNU General Public License. See the file COPYING for details. + */ /* lists.h 147 2007-04-09 00:44:09Z selinger */ #ifndef PCB_HID_GCODE_LISTS_H #define PCB_HID_GCODE_LISTS_H -/* here we define some general list macros. Because they are macros, - they should work on any datatype with a "->next" component. Some of - them use a "hook". If elt and list are of type t* then hook is of - type t**. A hook stands for an insertion point in the list, i.e., - either before the first element, or between two elements, or after - the last element. If an operation "sets the hook" for an element, - then the hook is set to just before the element. One can insert - something at a hook. One can also unlink at a hook: this means, - unlink the element just after the hook. By "to unlink", we mean the - element is removed from the list, but not deleted. Thus, it and its - components still need to be freed. */ - -/* Note: these macros are somewhat experimental. Only the ones that - are actually *used* have been tested. So be careful to test any - that you use. Looking at the output of the preprocessor, "gcc -E" - (possibly piped though "indent"), might help too. Also: these - macros define some internal (local) variables that start with - "_". */ - -/* we enclose macro definitions whose body consists of more than one - statement in MACRO_BEGIN and MACRO_END, rather than '{' and '}'. The - reason is that we want to be able to use the macro in a context - such as "if (...) macro(...); else ...". If we didn't use this obscure - trick, we'd have to omit the ";" in such cases. */ - +/*! + * \brief We enclose macro definitions whose body consists of more than + * one statement in MACRO_BEGIN and MACRO_END, rather than '{' and '}'. + * The reason is that we want to be able to use the macro in a context + * such as "if (...) macro(...); else ...". If we didn't use this + * obscure trick, we'd have to omit the ";" in such cases. + */ #define MACRO_BEGIN do { #define MACRO_END } while (0) /* ---------------------------------------------------------------------- */ /* macros for singly-linked lists */ -/* traverse list. At the end, elt is set to NULL. */ +/*! + * \brief Traverse list. At the end, elt is set to NULL. */ #define list_forall(elt, list) for (elt=list; elt!=NULL; elt=elt->next) -/* set elt to the first element of list satisfying boolean condition - c, or NULL if not found */ +/*! + * \brief Set elt to the first element of list satisfying boolean + * condition c, or NULL if not found. */ #define list_find(elt, list, c) \ MACRO_BEGIN list_forall(elt, list) if (c) break; MACRO_END -/* like forall, except also set hook for elt. */ +/*! + * \brief Like forall, except also set hook for elt. + */ #define list_forall2(elt, list, hook) \ for (elt=list, hook=&list; elt!=NULL; hook=&elt->next, elt=elt->next) -/* same as list_find, except also set hook for elt. */ +/*! + * \brief Same as list_find, except also set hook for elt. + */ #define list_find2(elt, list, c, hook) \ MACRO_BEGIN list_forall2(elt, list, hook) if (c) break; MACRO_END -/* same, except only use hook. */ +/*! + * \brief Same, except only use hook. + */ #define _list_forall_hook(list, hook) \ for (hook=&list; *hook!=NULL; hook=&(*hook)->next) -/* same, except only use hook. Note: c may only refer to *hook, not elt. */ +/*! + * \brief Same, except only use hook. + * + * \note c may only refer to *hook, not elt. + */ #define _list_find_hook(list, c, hook) \ MACRO_BEGIN _list_forall_hook(list, hook) if (c) break; MACRO_END -/* insert element after hook */ +/*! + * \brief Insert element after hook. + */ #define list_insert_athook(elt, hook) \ MACRO_BEGIN elt->next = *hook; *hook = elt; MACRO_END -/* insert element before hook */ +/*! + * \brief Insert element before hook. + */ #define list_insert_beforehook(elt, hook) \ MACRO_BEGIN elt->next = *hook; *hook = elt; hook=&elt->next; MACRO_END -/* unlink element after hook, let elt be unlinked element, or NULL. - hook remains. */ +/*! + * \brief Unlink element after hook, let elt be unlinked element, or + * NULL. hook remains. + */ #define list_unlink_athook(list, elt, hook) \ MACRO_BEGIN \ elt = hook ? *hook : NULL; if (elt) { *hook = elt->next; elt->next = NULL; }\ MACRO_END -/* unlink the specific element, if it is in the list. Otherwise, set - elt to NULL */ +/*! + * \brief Unlink the specific element, if it is in the list. Otherwise, + * set elt to NULL. + */ #define list_unlink(listtype, list, elt) \ MACRO_BEGIN \ listtype **_hook; \ @@ -86,11 +119,15 @@ list_unlink_athook(list, elt, _hook); \ MACRO_END -/* prepend elt to list */ +/*! + * \brief Prepend elt to list. + */ #define list_prepend(list, elt) \ MACRO_BEGIN elt->next = list; list = elt; MACRO_END -/* append elt to list. */ +/*! + * \brief Append elt to list. + */ #define list_append(listtype, list, elt) \ MACRO_BEGIN \ listtype **_hook; \ @@ -98,7 +135,9 @@ list_insert_athook(elt, _hook); \ MACRO_END -/* unlink the first element that satisfies the condition. */ +/*! + * \brief Unlink the first element that satisfies the condition. + */ #define list_unlink_cond(listtype, list, elt, c) \ MACRO_BEGIN \ listtype **_hook; \ @@ -106,23 +145,33 @@ list_unlink_athook(list, elt, _hook); \ MACRO_END -/* let elt be the nth element of the list, starting to count from 0. - Return NULL if out of bounds. */ +/*! + * \brief Let elt be the nth element of the list, starting to count from + * 0. + * + * \return NULL if out of bounds. + */ #define list_nth(elt, list, n) \ MACRO_BEGIN \ int _x; /* only evaluate n once */ \ for (_x=(n), elt=list; _x && elt; _x--, elt=elt->next) {} \ MACRO_END -/* let elt be the nth element of the list, starting to count from 0. - Return NULL if out of bounds. */ +/*! + * \brief Let elt be the nth element of the list, starting to count from + * 0. + * + * \return NULL if out of bounds. + */ #define list_nth_hook(elt, list, n, hook) \ MACRO_BEGIN \ int _x; /* only evaluate n once */ \ for (_x=(n), elt=list, hook=&list; _x && elt; _x--, hook=&elt->next, elt=elt->next) {} \ MACRO_END -/* set n to the length of the list */ +/*! + * \brief Set n to the length of the list. + */ #define list_length(listtype, list, n) \ MACRO_BEGIN \ listtype *_elt; \ @@ -131,8 +180,12 @@ n++; \ MACRO_END -/* set n to the index of the first element satisfying cond, or -1 if - none found. Also set elt to the element, or NULL if none found. */ +/*! + * \brief Set n to the index of the first element satisfying cond, or -1 + * if none found. + * + * Also set elt to the element, or NULL if none found. + */ #define list_index(list, n, elt, c) \ MACRO_BEGIN \ n=0; \ @@ -144,7 +197,10 @@ n=-1; \ MACRO_END -/* set n to the number of elements in the list that satisfy condition c */ +/*! + * \brief Set n to the number of elements in the list that satisfy + * condition c. + */ #define list_count(list, n, elt, c) \ MACRO_BEGIN \ n=0; \ @@ -153,11 +209,17 @@ } \ MACRO_END -/* let elt be each element of the list, unlinked. At the end, set list=NULL. */ +/*! + * \brief Let elt be each element of the list, unlinked. + * + * At the end, set list=NULL. + */ #define list_forall_unlink(elt, list) \ for (elt=list; elt ? (list=elt->next, elt->next=NULL), 1 : 0; elt=list) -/* reverse a list (efficient) */ +/*! + * \brief Reverse a list (efficient). + */ #define list_reverse(listtype, list) \ MACRO_BEGIN \ listtype *_list1=NULL, *elt; \ @@ -166,17 +228,24 @@ list = _list1; \ MACRO_END -/* insert the element ELT just before the first element TMP of the - list for which COND holds. Here COND must be a condition of ELT and - TMP. Typical usage is to insert an element into an ordered list: - for instance, list_insert_ordered(listtype, list, elt, tmp, - elt->size <= tmp->size). Note: if we give a "less than or equal" - condition, the new element will be inserted just before a sequence - of equal elements. If we give a "less than" condition, the new - element will be inserted just after a list of equal elements. - Note: it is much more efficient to construct a list with - list_prepend and then order it with list_merge_sort, than to - construct it with list_insert_ordered. */ +/*! + * \brief Insert the element ELT just before the first element TMP of + * the list for which COND holds. + * + * Here COND must be a condition of ELT and TMP. + * Typical usage is to insert an element into an ordered list: + * for instance, list_insert_ordered(listtype, list, elt, tmp, + * elt->size <= tmp->size). + * + * \note If we give a "less than or equal" condition, the new element + * will be inserted just before a sequence of equal elements. + * If we give a "less than" condition, the new element will be inserted + * just after a list of equal elements. + * + * \note It is much more efficient to construct a list with list_prepend + * and then order it with list_merge_sort, than to construct it with + * list_insert_ordered. + */ #define list_insert_ordered(listtype, list, elt, tmp, cond) \ MACRO_BEGIN \ listtype **_hook; \ @@ -184,13 +253,17 @@ list_insert_athook(elt, _hook); \ MACRO_END -/* sort the given list, according to the comparison condition. - Typical usage is list_sort(listtype, list, a, b, a->size < - b->size). Note: if we give "less than or equal" condition, each - segment of equal elements will be reversed in order. If we give a - "less than" condition, each segment of equal elements will retain - the original order. The latter is slower but sometimes - prettier. Average running time: n*n/2. */ +/*! + * \brief Sort the given list, according to the comparison condition. + * + * Typical usage is list_sort(listtype, list, a, b, a->size < b->size). + * + * \note If we give "less than or equal" condition, each segment of + * equal elements will be reversed in order. If we give a "less than" + * condition, each segment of equal elements will retain the original + * order. The latter is slower but sometimes prettier. Average running + * time: n*n/2. + */ #define list_sort(listtype, list, a, b, cond) \ MACRO_BEGIN \ listtype *_newlist=NULL; \ @@ -199,11 +272,15 @@ list = _newlist; \ MACRO_END -/* a much faster sort algorithm (merge sort, n log n worst case). It - is required that the list type has an additional, unused next1 - component. Note there is no curious reversal of order of equal - elements as for list_sort. */ - +/*! + * \brief A much faster sort algorithm (merge sort, n log n worst case). + * + * It is required that the list type has an additional, unused next1 + * component. + * + * \note There is no curious reversal of order of equal elements as for + * list_sort. + */ #define list_mergesort(listtype, list, a, b, cond) \ MACRO_BEGIN \ listtype *_elt, **_hook1; \ @@ -223,7 +300,11 @@ } while (_hook1 != &(list)); \ MACRO_END -/* merge two sorted lists. Store result at &result */ +/*! + * \brief Merge two sorted lists. + * + * Store result at &result. + */ #define _list_merge_cond(listtype, a, b, cond, result) \ MACRO_BEGIN \ listtype **_hook; \ @@ -262,11 +343,17 @@ end = elt; \ MACRO_END -/* let elt be each element of the list, unlinked. At the end, set list=NULL. */ +/*! + * \brief Let elt be each element of the list, unlinked. + * + * At the end, set list=NULL. + */ #define dlist_forall_unlink(elt, head, end) \ for (elt=head; elt ? (head=elt->next, elt->next=NULL, elt->prev=NULL), 1 : (end=NULL, 0); elt=head) -/* unlink the first element of the list */ +/*! + * \brief Unlink the first element of the list. + */ #define dlist_unlink_first(head, end, elt) \ MACRO_BEGIN \ elt = head; \ -- 2.11.4.GIT