More comments in common/

1 files changed, 23 insertions, 2 deletions

diff --git a/common/eurephia_directions.h b/common/eurephia_directions.h
index 5eccf46..fa2adba 100644
--- a/common/eurephia_directions.h
+++ b/common/eurephia_directions.h
@@ -19,11 +19,32 @@
  *
  */
 
+/**
+ * @file   eurephia_directions.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Macro to decide the best search directon on dual-way
+ *         ring based pointer chains
+ *
+ */
+
 #ifndef _EUREPHIA_DIRECTIONS_H
 #define _EUREPHIA_DIRECTIONS_H
 
-#define DIR_R 'R'
-#define DIR_L 'L'
+#define DIR_R 'R'		/**< "Right" direction, where the ID number increases (next element)    */
+#define DIR_L 'L'		/**< "Left" direction, where the ID number decreases (previous element) */
+
+/**
+ * This macro finds the quickest way to go from one element to another one in
+ * a circular dual-way pointer chain, based on a numeric id of the elements.
+ *
+ * @param s starting point on the chain
+ * @param d destination point on the chain
+ * @param l number of elements in the chain
+ *
+ * @return Returns DIR_R or DIR_L, depending on what will be the shortest distance.
+ */
 #define DIRECTION(s,d,l) (s>d ? ((((l-s)+d) > (s-d)) ? DIR_L : DIR_R) : (((d-s) > ((l-d)+s)) ? DIR_L : DIR_R))
 
 #endif