1 files changed, 73 insertions, 56 deletions
diff --git a/runtime/map.doc b/runtime/map.doc
index 94d9ffdd..6a1585b7 100644
--- a/runtime/map.doc
+++ b/runtime/map.doc
@@ -1,7 +1,48 @@
-/* This is for documentation only.  Do not compile. */
-/* -*- linux-c -*- */
-
+/** @addtogroup maps Maps (Associative Arrays)
+
+Maps are implemented as hash lists. In order to efficiently handle maps with up to five keys of any combination
+of int64s and strings, the functions to create maps, set keys, and set and get values
+are all generated as needed.  To do this, you must simply do some defines and 
+include the proper files.  For example, if you need a map with 3 keys, int64, int64, and string
+that stores strings, you need to do
+@code
+
+#define NEED_STRING_VALS
+
+#define KEY1_TYPE INT64
+#define KEY2_TYPE INT64
+#define KEY3_TYPE STRING
+#include "map-keys.c"
+
+#include "map.c"
+@endcode
+
+In the above example, maps are created with _stp_map_new_int64_int64_str(). All the
+generated functions start with a base name (such as _stp_map_new) and add the key types separated
+by underscores.
+
+Each map can hold only one type of data; int64, string, or statistics.  Each element belonging to a map can have up to 
+5 keys and a value.  Implemented key types are strings and int64.
+	
+To simplify the implementation, the functions to set the key and the functions to set the data are separated.
+The map remembers what the current key is.
+For example, to continue our previous example,
+@code
+/* create a map with a max of 100 elements containing strings */
+MAP mymap = _stp_map_new_int64_int64_str(100, STRING);
+
+/* mymap[100, 300, "Ohio"] = "Columbus" */
+_stp_map_key_int64_int64_str (mymap, 100, 300, "Ohio");
+_stp_map_set_str (mymap, "Columbus");
+@endcode
+
+All elements have a default value of 0 (or NULL).  Elements are only saved to the map when their value is set
+to something nonzero.  
+
+For good examples, see the runtime/tests/maps directory or the example probes.
 */
+
+
 /** @addtogroup maps
  *
  * @{
@@ -79,34 +120,6 @@ void _stp_map_set_str (MAP map, char *val) {}
  */
 void _stp_map_set_string (MAP map, String str){}
 
-/** Set the current element's value to an int64.
- * This sets the current element's value to an int64. The map must have been created
- * to hold int64s using <i>_stp_map_new_(xxx, INT64)</i>
- *
- * If the element doesn't exist, it is created.  If no current element (key)
- * is set for the map, this function does nothing.
- * @param map
- * @param val new value
- * @sa _stp_map_add_int64()
- * @sa _stp_map_set()
- */
-void _stp_map_set_int64 (MAP map, int64_t val) {}
-
-/** Set the current element's value to a stat.
- * This sets the current element's value to an stat struct. The map must have been created
- * to hold stats using <i>_stp_map_new_(xxx, STAT)</i> (or HSTAT_LOG or HSTAT_LINEAR).  This function would only be used
- * if you want to set stats to something other than the normal initial values (count = 0,
- * sum = 0, etc).
- * @sa _stp_map_add_stat
- * @sa _stp_map_add_int64_stat
- *
- * If the element doesn't exist, it is created.  If no current element (key)
- * is set for the map, this function does nothing.
- * @param map
- * @param val pointer to stats struct.
- */
-void _stp_map_set_stat (MAP map, stat *val) {}
-
 /** Appends a C string to the current element's value
  * This appends a C string to the current element's value. The map must have been created
  * to hold strings using <i>_stp_map_new_(xxx, STRING)</i>
@@ -130,31 +143,6 @@ void _stp_map_add_str (MAP map, char *val) {}
  * @sa _stp_map_set_int64()
  */
 void _stp_map_add_int64 (MAP map, int64_t val) {}
-
-/** Add stats to the current element's value.
- * This adds stats to the current element's value to an stat struct. The map must have been created
- * to hold stats using <i>_stp_map_new_(xxx, STAT)</i> (or HSTAT_LOG or HSTAT_LINEAR).  This function would only be used
- * to combine stats from multiple sources into a single stats struct.
- * @sa _stp_map_add_stat
- * @sa _stp_map_add_int64_stat
- *
- * If the element doesn't exist, it is created.  If no current element (key)
- * is set for the map, this function does nothing.
- * @param map
- * @param val pointer to stats struct.
- */
-void _stp_map_add_stat (MAP map, stat *val) {}
-
-/** Add an int64 to the current element's statistics.
- * Increments the statistics counter by one and the sum by <i>val</i>.
- * Adjusts minimum, maximum, and histogram.
- *
- * If the element doesn't exist, it is created.  If no current element (key)
- * is set for the map, this function does nothing.
- * @param map
- * @param val value to add to the statistics
- */
-void _stp_map_add_int64_stat (MAP map, int64_t val){}
 /** @} end of map_set group*/
 
 /** @defgroup map_get Getting the Values from Maps
@@ -189,3 +177,32 @@ int64_t _stp_map_get_int64 (MAP map) {}
 
 /** @} end of map_get group */
 /** @} */
+
+/** @page format_string Format Strings
+Format strings for maps and stats use a special format string. Be careful 
+not to confuse it with a printf-style format.
+@verbatim
+--- KEYS and RESULTS ---
+%p - address (hex padded to sizeof(void *))
+%P - symbolic address
+%x - hex int64
+%X - HEX int64
+%d - decimal int64
+%s - string
+--- STATS ---
+%m - min
+%M - max
+%A - avg
+%S - sum
+%H - histogram
+%C - count
+--- MISC ---
+%% - print '%'
+--- PER_CPU ---
+%c - CPU number
+@endverbatim
+When printing map keys, format types are preceeded by a single-digit number 
+indicating the key number. For example, "%1d,%2s" prints key 1 as an int64 followed by
+key 2 as a string. Here's a good example from the test files.
+@include map_format.c
+*/