Improve documentation

scripting/include/more_adt.inc

@@ -2,24 +2,61 @@
 	#endinput
 #endif
 
+#define __more_adt_ext
+
 /**
  * An iterator for the StringMultiMap.
  * Call its Next() function before performing any retrievals to ensure that it is valid.
  */
 methodmap StringMultiMapIterator < Handle {
+	/**
+	 * Advances the iterator to the next key / value.
+	 * Returns false when the iterator has been exhausted.
+	 */
 	public native bool Next();
+
+	/**
+	 * Returns the key at the current position.
+	 */
 	public native void GetKey(char[] name, int maxlen);
 
 	/** 
-	 * Returns the string at the current iterator position.
+	 * Retrieves the string at the current iterator position, storing it in the specified
+	 * buffer.
+	 * Returns false if the current position contains a cell value or array.
 	 */
 	public native bool GetString(char[] value, int max_size, int& size = 0);
+
+	/**
+	 * Assigns the given string to the current iterator position, replacing any value
+	 * previously set.
+	 */
 	public native void SetString(const char[] value);
 
+	/**
+	 * Retrieves the single cell value at the current iterator position, storing it in the
+	 * specified cell reference.
+	 * Returns false if the current position contains a string or a cell array.
+	 */
 	public native bool GetValue(any &value);
+
+	/**
+	 * Assigns the given cell value to the current iterator position, replacing any value
+	 * previously set.
+	 */
 	public native void SetValue(any value);
 
+	/**
+	 * Retrieves the cell array at the current iterator position, storing it in the specified
+	 * array.
+	 * Returns false if the current position contains a string or a cell array.
+	 */
 	public native bool GetArray(any[] array, int max_size, int& size = 0);
+
+	/**
+	 * Assigns the cell array to the current iterator position, replacing any value
+	 * previously set.
+	 */
 	public native void SetArray(const any[] array, int num_items);
 
 	/**
@@ -32,9 +69,9 @@ methodmap StringMultiMapIterator < Handle {
 /**
  * Creates a multimap.  A multimap is a container that can map keys to arbitrary values.
  * 
- * There can be multiple entries in a multimap for a given key; only the first inerted entry
- * will be accessible through the Get*() methods.  To retrieve all the entries for a given key,
- * use the GetKeyIterator() method to get an iterator over the specified key.
+ * There can be multiple entries in a multimap for a given key; however, only the first inserted
+ * entry will be accessible through the Get*() methods.  To retrieve all the entries for a given
+ * key, use the GetKeyIterator() method to get an iterator over the specified key.
  */
 methodmap StringMultiMap < Handle {
 	public native StringMultiMap();
@@ -66,8 +103,16 @@ methodmap StringMultiMap < Handle {
 	 */
 	public native bool GetString(const char[] key, char[] value, int max_size, int& size = 0);
 
+	/**
+	 * Adds a new cell array with the specified key.
+	 */
 	public native void AddArray(const char[] key, const any[] array, int num_items);
-	public native void GetArray(const char[] key, any[] array, int max_size, int& size = 0);
+
+	/**
+	 * Returns true iff the first entry associated with a key is a cell value, filling the
+	 * passed-in `value` buffer.
+	 */
+	public native bool GetArray(const char[] key, any[] array, int max_size, int& size = 0);
 
 	/**
 	 * Returns an interator over all keys.  Will still return a valid StringMultiMapIterator
@@ -77,7 +122,6 @@ methodmap StringMultiMap < Handle {
 
 	/**
 	 * Returns an iterator for elements matching a specific key.
-	 * (Wrapper for std::multimap::equal_range.)
 	 */
 	public native StringMultiMapIterator GetKeyIterator(const char[] key);
 }