documentation, remove LIFO_DEBUG, break main

add documentation to lifo.h
remove LIFO_DEBUG and use DEVELHELP instead
make the main method which is included break

core/include/lifo.h

@@ -11,17 +11,52 @@
  * @{
  *
  * @file        lifo.h
- * @brief       LIFO buffer API
+ * @brief       LIFO buffer API, read long description carefully
+ * @author      probably Kaspar Schleiser
  *
- * @author      unknwon
+ * @long        This LIFO implementation very efficiently handles
+ *              integer values. The caveat is that it can only handle
+ *              values between 0 and its own size -1. Also it can only
+ *              handle up to one element of each value. I.e. you can
+ *              not insert a value twice or the LIFO will break.
  */
 
 #ifndef __LIFO_H
 #define __LIFO_H
 
+/**
+ * @brief:  check if the given lifo is empty
+ * @return: true if empty, false otherwise
+ */
 int lifo_empty(int *array);
+
+/**
+ * @brief:           initialize a lifo array
+ *
+ * @param array:     an array of int of size n+1
+ * @param n:         maximum integer value the lifo is able to store
+ */
 void lifo_init(int *array, int n);
+
+/**
+ * @brief:          insert an element into the lifo
+ *
+ * @param array:    an integer array of least i+1 size that does not
+ *                  already contain i 
+ * @param i:        the integer value to store, between 0 and the size
+ *                  of the array -1, must not be stored already
+ *
+ */
 void lifo_insert(int *array, int i);
+
+/**
+ * @brief:          extract the least recently inserted element from the lifo
+ * 
+ * @param array:    an integer array
+ *
+ * @return:         -1 if the lifo is empty, the least recently
+ *                  inserted elment otherwise
+ */
 int lifo_get(int *array);
 
 /** @} */

core/lifo.c

@@ -9,22 +9,15 @@
 /**
  * @ingroup     core_util
  * @{
- *
- * @file        lifo.c
- * @brief       LIFO buffer implementation
- *
  * @file        lifo.c
  * @brief       LIFO buffer implementation
- * @author      unknown
+ * @author      probably Kaspar Schleiser
  * @}
  */
 
 #include "lifo.h"
 
 #define ENABLE_DEBUG (0)
-#if ENABLE_DEBUG
-#define DEBUG_LIFO 1
-#endif
 #include "debug.h"
 
 int lifo_empty(int *array)
@@ -46,10 +39,10 @@ void lifo_insert(int *array, int i)
 
     int index = i + 1;
 
-#if DEBUG_LIFO
+#if DEVELHELP
     for (int x=0; x < index; x++) {
         if (i == array[x]) {
-            printf("lifo_insert: inserting duplicate into lifo: %d\n", i);
+            printf("\nlifo_insert: inserting duplicate into lifo: %d\n\n\n\t\tThe lifo is broken now.\n\n\n", i);
         }
     }
     if ((array[index] != -1) && (array[0] != -1)) {
@@ -93,6 +86,7 @@ int main()
     lifo_insert(array, 1);
     lifo_insert(array, 3);
     lifo_insert(array, 0);
+    lifo_insert(array, 0);
     printf("get: %i\n", lifo_get(array));
     printf("get: %i\n", lifo_get(array));
     printf("get: %i\n", lifo_get(array));