diff include/Utilities.h @ 66:74a44c3d91f0 newapi

Some initial, partial documentation in Utilities.h

--- a/include/Utilities.h	Wed Jul 15 20:04:02 2015 +0100
+++ b/include/Utilities.h	Wed Jul 15 23:55:48 2015 +0100
@@ -1,8 +1,13 @@
-/*
- * Utilities.h
+/**
+ *  @file
+ *  @brief Wiring-inspired utility functions and macros
  *
- *  Created on: Oct 27, 2014
- *      Author: parallels
+ *  Macros and functions for I/O and data processing taking after the Wiring
+ *  (Arduino) language. This code began as part of the Hackable Instruments
+ *  project (EPSRC) at Queen Mary University of London, 2013-14.
+ *
+ *  (c) 2014-15 Andrew McPherson, Victor Zappi and Giulio Moro,
+ *  Queen Mary University of London
  */
 
 #ifndef UTILITIES_H_
@@ -10,9 +15,16 @@
 
 #include "BeagleRT.h"
 
+/// Set the given bit in \c word to 1.
 #define setBit(word,bit) 			((word) | (1 << (bit)))
+
+/// Clear the given bit in \c word to 0.
 #define clearBit(word,bit) 			((word) &~ (1 << (bit)))
+
+/// Check if the given bit in \c word is 1 (returns nonzero) or 0 (returns zero).
 #define getBit(word,bit) 			(((word) >> (bit)) & 1)
+
+/// Set/clear the given bit in \c word to \c value.
 #define changeBit(word,bit,value) 	((clearBit((word),(bit))) | ((value) << (bit)))
 
 #if 1
@@ -67,7 +79,42 @@
 
 #endif
 
+/**
+ * \brief Linearly rescale a number from one range of values to another.
+ *
+ * This function linearly scales values of \c x such that the range in_min to
+ * in_max at the input corresponds to the range out_min to out_max
+ * at the output. Values outside this range are extrapolated.
+ *
+ * This function behaves identically to the function of the same name in Processing. It
+ * is also similar to the corresponding function in Arduino, except that it supports floating
+ * point values.
+ *
+ * \param x Input value to be mapped.
+ * \param in_min Lower bound of the input range.
+ * \param in_max Upper bound of the input range.
+ * \param out_min Lower bound of the output range.
+ * \param out_max Upper bound of the output range.
+ * \return Rescaled value.
+ */
 float map(float x, float in_min, float in_max, float out_min, float out_max);
+
+/**
+ * \brief Constrain a number to stay within a given range.
+ *
+ * This function constrains \c x to remain within the range min_val to
+ * max_val. Values of \c x outside this range are clipped to the edges
+ * of the range.
+ *
+ * This function behaves identically to the function of the same name in Processing. It
+ * is also similar to the corresponding function in Arduino, except that it supports floating
+ * point values.
+ *
+ * \param x Input value to be constrained.
+ * \param min_val Minimum possible value.
+ * \param max_val Maximum possible value.
+ * \return Constrained value.
+ */
 float constrain(float x, float min_val, float max_val);
 
 #endif /* UTILITIES_H_ */