Header lib: refactor inven_as_array and add proper jsdoc defs to all comments

- inven_as_array was allocating blocks of 100 items which was unnecessary
2026-07-27 16:52:34 -07:00 · 2024-05-20 20:20:56 +08:00
parent 3c8ec03e30
commit 0746d6b483
6 changed files with 237 additions and 61 deletions
@@ -163,6 +163,8 @@ end

 /**
 * Returns first index of zero value in a list array.
+ * @arg {list} array
+ * @ret {int}
 */
 procedure get_empty_array_index(variable array) begin
   variable zero := false;
@@ -178,7 +180,10 @@ procedure get_empty_array_index(variable array) begin
 end

 /**
- * Pushes new item to the end of a list array.
+ * Pushes new item to the end of a list array and returns the array.
+ * @arg {list} array
+ * @arg {any} item
+ * @ret {list}
 */
 procedure array_push(variable array, variable item) begin
   variable n;
@@ -190,6 +195,8 @@ end

 /**
 * Removes last item from list array (reducing it's size by 1) and returns it's value.
+ * @arg {list} array
+ * @ret {mixed}
 */
 procedure array_pop(variable array) begin
   variable n, ret;
@@ -204,6 +211,8 @@ end

 /** 
 * Returns a temp list of keys from a given map array.
+ * @arg {array}
+ * @ret {list}
 */
 procedure array_keys(variable array) begin
   variable tmp, i, len;
@@ -219,6 +228,8 @@ end

 /**
 * Returns a temp list of values from a given map array.
+ * @arg {array} array
+ * @ret {array}
 */
 procedure array_values(variable array) begin
   variable v, tmp, i, len;
@@ -234,6 +245,8 @@ end

 /**
 * Sets given array as permanent and returns it.
+ * @arg {array} array
+ * @ret {array}
 */
 procedure array_fixed(variable array) begin
   fix_array(array);
@@ -242,6 +255,10 @@ end

 /**
 * Returns a slice of a given list array as a new temp array.
+ * @arg {list} array
+ * @arg {int} index - Start position to slice from.
+ * @arg {int} count - Number of elements to slice.
+ * @ret {list}
 */
 procedure array_slice(variable array, variable index, variable count) begin
   variable tmp, i, n;
@@ -261,7 +278,11 @@ procedure array_slice(variable array, variable index, variable count) begin
 end

 /**
- * Removes a slice of given list array.
+ * Removes a slice of given list array and returns it.
+ * @arg {list} array
+ * @arg {int} index - Start position to remove from.
+ * @arg {int} count - Number of elements to remove.
+ * @ret {list}
 */
 procedure array_cut(variable array, variable index, variable count) begin
   variable i, n;
@@ -281,7 +302,10 @@ procedure array_cut(variable array, variable index, variable count) begin
 end

 /**
- * Removes all values in arr1 that also present in arr2.
+ * Removes all values in arr1 that also present in arr2 and returns arr1.
+ * @arg {array} arr1
+ * @arg {array} arr2
+ * @ret {array}
 */
 procedure array_diff(variable arr1, variable arr2) begin
   variable i, v, isMap;
@@ -300,6 +324,11 @@ end

 /**
 * Copy a slice of one array into another (will not resize)
+ * @arg {list} src - Source array.
+ * @arg {int} srcPos - Position in source array.
+ * @arg {list} dest - Destination array.
+ * @arg {int} dstPos - Position in destination array.
+ * @arg {int} size - Number of elements to copy.
 */
 procedure copy_array(variable src, variable srcPos, variable dest, variable dstPos, variable size) begin
  variable i := 0;
@@ -312,6 +341,8 @@ end

 /**
 * Creates a shallow copy of the array as a new temp array.
+ * @arg {array} array
+ * @ret {array}
 */
 procedure clone_array(variable array) begin
   variable new, k, v;
@@ -327,6 +358,9 @@ end

 /**
 * Compares two arrays (list or map) and returns true if they have identical values in the same order.
+ * @arg {array} arr1
+ * @arg {array} arr2
+ * @ret {bool}
 */
 procedure arrays_equal(variable arr1, variable arr2) begin
   variable n, i, k1, k2;
@@ -350,6 +384,8 @@ end

 /**
 * Returns maximum element in array.
+ * @arg {array} arr
+ * @ret {mixed}
 */
 procedure array_max(variable arr) begin
   variable v, max;
@@ -363,6 +399,8 @@ end

 /**
 * Returns minimum element in array.
+ * @arg {array} arr
+ * @ret {mixed}
 */
 procedure array_min(variable arr) begin
   variable v, min;
@@ -376,6 +414,8 @@ end

 /**
 * Returns sum of array elements (or concatenated string, if elements are strings).
+ * @arg {array} arr
+ * @ret {mixed}
 */
 procedure array_sum(variable arr) begin
   variable v, sum;
@@ -388,6 +428,8 @@ end

 /**
 * Returns a random value from a given list array.
+ * @arg {list} arr
+ * @ret {any}
 */
 procedure array_random_value(variable arr) begin
   return get_array(arr, array_key(arr, random(0, len_array(arr) - 1)));
@@ -399,6 +441,9 @@ end
 /**
 * Array set is a list array that is used as a set of unique values (where no diplicate value is allowed).
 * Tries to add new value to a set and returns true if it was just added.
+ * @arg {list} array - List array to use as a set.
+ * @arg {any} item
+ * @ret {bool}
 */
 procedure add_array_set(variable array, variable item) begin
   variable i := 0;
@@ -428,6 +473,9 @@ end

 /**
 * Remove value from a set (list array). Returns true if item was actually found and removed.
+ * @arg {list} array - List array to use as a set.
+ * @arg {any} item
+ * @ret {bool}
 */
 procedure remove_array_set(variable array, variable item) begin
   variable i := 0;
@@ -455,9 +503,10 @@ end
 #undef ARRAY_SET_BLOCK_SIZE

 /**
-   Creates a new array filled from a given array by transforming each value using given procedure name.
-   - *arr* - Array to use values from.
-   - *valueFunc* - A name of procedure that accepts value from arr and returns a new value.
+ * Creates a new array filled from a given array by transforming each value using given procedure name.
+ * @arg {array} arr - Array to use values from.
+ * @arg {string} valueFunc - A name of procedure that accepts value from arr and returns a new value.
+ * @ret {array}
 */
 procedure array_transform(variable arr, variable valueFunc) begin
   variable k, v, retArr := temp_array_map if array_is_map(arr) else temp_array(len_array(arr), 0);
@@ -468,10 +517,11 @@ procedure array_transform(variable arr, variable valueFunc) begin
 end

 /**
-   Creates a new temp array filled from a given array by transforming each key and value using given procedure name.
-   - *arr* - Array to use keys and values from.
-   - *keyFunc* - A name of procedure that accepts key from arr and returns a new key for the new array.
-   - *valueFunc* - A name of procedure that accepts value from arr and returns a new value.
+ * Creates a new temp array filled from a given array by transforming each key and value using given procedure name.
+ * @arg {array} arr - Array to use keys and values from.
+ * @arg {string} keyFunc - A name of procedure that accepts key from arr and returns a new key for the new array.
+ * @arg {string} valueFunc - A name of procedure that accepts value from arr and returns a new value.
+ * @ret {map}
 */
 procedure array_transform_kv(variable arr, variable keyFunc, variable valueFunc) begin
   variable k, v, retArr := temp_array_map;
@@ -483,6 +533,8 @@ end

 /**
 * Converts given array into a new map where keys are array values and all values are 1.
+ * @arg {array} arr
+ * @ret {array}
 */
 procedure array_to_set(variable arr) begin
   variable v, retArr := temp_array_map;
@@ -497,8 +549,10 @@ end

 /**
 * Adds new empty place for a new block into array. Returns index of new block that was "created".
- * 
- * DEPRECATED, use collections instead
+ * @arg {list} arr - array to add "block" into
+ * @arg {int} blocksize - block size
+ * @ret {int} - index of added block
+ * @deprecated - use collections instead
 */
 procedure add_array_block(variable arr, variable blocksize) begin
   variable begin
@@ -526,8 +580,10 @@ end

 /**
 * Removes a block from an array by index
- * 
- * DEPRECATED, use collections instead
+ * @arg {list} arr - array to remove "block" from
+ * @arg {int} blocksize - block size
+ * @arg {int} index - index to remove
+ * @deprecated - use collections instead
 */
 procedure remove_array_block(variable arr, variable blocksize, variable index) begin
   variable len;
@@ -547,9 +603,10 @@ end

 /**
 * Fill array (or it's part) with the same value.
- * pos - starting position;
- * count - number of items to fill (use -1 to fill to the end of the array);
- * value - value to set;
+ * @arg {list} arr
+ * @arg {int} pos - starting position
+ * @arg {int} count - number of items to fill (use -1 to fill to the end of the array);
+ * @arg {any} value - value to set;
 */
 procedure array_fill(variable arr, variable pos, variable count, variable value) begin
   variable i := 0;
@@ -563,6 +620,9 @@ end

 /**
 * Adds all the values of the second array to the first array.
+ * @arg {array} arr1
+ * @arg {array} arr2
+ * @ret {array} - the first array after modification
 */
 procedure array_append(variable arr1, variable arr2) begin
   variable arr1_len;
@@ -581,6 +641,9 @@ end

 /**
 * Loads a "saved" array. If it doesn't exist, creates it (with a given size).
+ * @arg {string} name - saved array name/key
+ * @arg {int} size - size of array to create
+ * @ret {array} - the created/loaded array
 */
 procedure load_create_array(variable name, variable size) begin
   variable arr;
@@ -594,6 +657,9 @@ end

 /**
 * Creates and returns a new "saved" array. If array already existed with this name, frees it.
+ * @arg {string} name - saved array name/key
+ * @arg {int} size - size of array to create
+ * @ret {array} - the new array
 */
 procedure get_saved_array_new(variable name, variable size) begin
   variable arr;
@@ -609,6 +675,8 @@ end

 /**
 * A collection is a 2-level-deep saved array (a saved array containing other saved arrays as values).
+ * @arg {string} name - name/key of a "root" array
+ * @arg {array} arr - collection array
 */
 procedure save_collection(variable name, variable arr) begin
   variable k, v, keys, oldKeys;
@@ -625,6 +693,11 @@ procedure save_collection(variable name, variable arr) begin
   end
 end

+/**
+ * Loads collection by name.
+ * @arg {string} name - name/key of a "root" array
+ * @ret {array}
+ */
 procedure load_collection(variable name) begin
   variable k, v, keys, arr;
   keys := load_array(name);
@@ -645,7 +718,10 @@ end
 */

 /**
- * Prints array contents with a given level of recursion.
+ * Formats array contents into a string with a given level of recursion. For debugging.
+ * @arg {array} arr
+ * @arg {int} levels - recursion level
+ * @ret {string}
 */
 procedure debug_array_str_deep(variable arr, variable levels) begin
 #define _newline if (levels > 1) then s += "\n";
@@ -4,26 +4,33 @@

 #include "define_lite.h"
 #include "define_extra.h"
+
 #define PID_BOTTLE_CAPS                     (41)

 /**
 * Inventory contents as temp array to be used in foreach
+ * @arg {ObjectPtr} critter
+ * @ret {list}
 */
 procedure inven_as_array(variable critter) begin
-   variable i:=0, list;
-   list := temp_array(100, 4);
-   while (inven_ptr(critter, i)) do begin
-      if (i>=len_array(list)) then
-         resize_array(list, len_array(list) + 100);
-      list[i] := inven_ptr(critter, i);
+   variable i := 0, list, item;
+   list := temp_array(0, 4);
+   item := inven_ptr(critter, i);
+   while (item) do begin
+      resize_array(list, i + 1);
+      list[i] := item;
      i++;
+      item := inven_ptr(critter, i);
   end
-   resize_array(list, i);
   return list;
 end

 /**
- * Adds quantity of itemPid to invenObj.
+ * Adds quantity of itemPid to invenObj and returns the created item object.
+ * @arg {ObjectPtr} invenObj - Object to add new item to.
+ * @arg {int} itemPid - PID of item.
+ * @arg {int} quantity
+ * @ret {ObjectPtr} - created item
 */
 procedure add_items_pid(variable invenObj, variable itemPid, variable quantity) begin
   variable item;
@@ -34,6 +41,9 @@ end

 /**
 * Adds 1 item of a given pid to obj.
+ * @arg {ObjectPtr} obj - Object to add new item to.
+ * @arg {int} pid
+ * @ret {ObjectPtr}
 */
 #define add_item_pid(obj, pid)            add_items_pid(obj, pid, 1)

@@ -43,6 +53,7 @@ end

 /**
 * Makes critter remove his armor and put it back to his inventory.
+ * @arg {ObjectPtr} critter
 */
 procedure unwield_armor(variable critter) begin
   variable armor;
@@ -55,12 +66,11 @@ procedure unwield_armor(variable critter) begin
 end

 /**
-   Removes items of given pid from given object's inventory.
-   - *invenObj* - obj to remove items from
-   - *itemPid* - PID of item to remove
-   - *quantity* - maximum quantity of items to remove (-1 to remove all available items)
-
-   Returns number of actually removed items.
+ * Removes items of given pid from given object's inventory. Returns number of actually removed items.
+ * @arg {ObjectPtr} invenObj - obj to remove items from
+ * @arg {int} itemPid - PID of item to remove
+ * @arg {int} quantity - maximum quantity of items to remove (-1 to remove all available items)
+ * @ret {int}
 */
 procedure remove_items_pid(variable invenObj, variable itemPid, variable quantity) begin
   variable begin
@@ -90,8 +100,10 @@ procedure remove_items_pid(variable invenObj, variable itemPid, variable quantit
 end

 /**
-   Remove the whole stack of a given *item* object from *invenObj* inventory.
-   For a critter, this will correctly remove item from armor/hand slot, if it is equipped.
+ * Remove the whole stack of a given *item* object from *invenObj* inventory.
+ * For a critter, this will correctly remove item from armor/hand slot, if it is equipped.
+ * @arg {ObjectPtr} invenObj - obj to remove from
+ * @arg {ObjectPtr} item - item (stack) object to remove
 */
 procedure remove_item_obj(variable invenObj, variable item) begin
   if (obj_type(invenObj) == OBJ_TYPE_CRITTER) then begin
@@ -106,36 +118,52 @@ procedure remove_item_obj(variable invenObj, variable item) begin
 end

 /**
-   Remove one item of a given *pid* from *obj* inventory.
+ * Remove one item of a given *pid* from *obj* inventory.
+ * @arg {ObjectPtr} obj - obj to remove items from
+ * @arg {int} pid - PID of item to remove
+ * @ret {int}
 */
 #define remove_item_pid(obj, pid)            remove_items_pid(obj, pid, 1)

 /**
-   Remove all items of a given *pid* from *obj* inventory.
+ * Remove all items of a given *pid* from *obj* inventory. Returns number of removed items.
+ * @arg {ObjectPtr} obj - obj to remove items from
+ * @arg {int} pid - PID of item to remove
+ * @ret {int}
 */
 #define remove_all_items_pid(obj, pid)       remove_items_pid(obj, pid, -1)

 /**
-   Ensures a given *quantity* of *itemPid* in *invenObj* inventory, adding or removing items as necessary.
+ * Ensures a given *quantity* of *itemPid* in *invenObj* inventory, adding or removing items as necessary.
+ * @arg {ObjectPtr} invenObj - obj to add/remove items to/from
+ * @arg {int} itemPid - PID of item to remove
+ * @arg {int} quantity
 */
-procedure set_items_qty_pid(variable invenObj, variable itempid, variable quantity)
+procedure set_items_qty_pid(variable invenObj, variable itemPid, variable quantity)
 begin
   variable begin
      count;
      obj;
   end
-   count := obj_is_carrying_obj_pid(invenObj, itempid);
+   count := obj_is_carrying_obj_pid(invenObj, itemPid);
   if (quantity > count) then begin
-      obj := create_object_sid(itempid, 0, 0, -1);
+      obj := create_object_sid(itemPid, 0, 0, -1);
      add_mult_objs_to_inven(invenObj, obj, quantity - count);
   end else if (quantity < count) then begin
-      call remove_items_pid(invenObj, itempid, count - quantity);
+      call remove_items_pid(invenObj, itemPid, count - quantity);
   end
 end

 /**
-   Removes money and items from a *critter*'s inventory, using provided probabilities (applied to whole stacks, not individual items).
-   Useful for reducing loot of merchants after death.
+ * Removes money and items from a *critter*'s inventory, using provided probabilities (applied to whole stacks, not individual items).
+ * Useful for reducing loot of merchants after death.
+ * @arg {ObjectPtr} critter
+ * @arg {int} moneyPercent - Percent of money to remove. 
+ * @arg {int} probArmor - % probability to remove armor.
+ * @arg {int} probDrugs - % probability to remove drugs.
+ * @arg {int} probWeapons - % probability to remove weapons.
+ * @arg {int} probAmmo - % probability to remove ammo.
+ * @arg {int} probMisc - % probability to remove misc item.
 */
 procedure reduce_merchant_loot(variable critter, variable moneyPercent, variable probArmor, variable probDrugs, variable probWeapons, variable probAmmo, variable probMisc) begin
   variable inv, item, it, prob, tmp;
@@ -164,7 +192,10 @@ procedure reduce_merchant_loot(variable critter, variable moneyPercent, variable
 end

 /**
-   Returns item in one of *critter*'s hand slots using given attack type.
+ * Returns item in one of *critter*'s hand slots using given attack type.
+ * @arg {ObjectPtr} critter
+ * @arg {int} type - Attack Type, see ATKTYPE_* in define_extra.h
+ * @ret {ObjectPtr}
 */
 procedure item_by_attack_type(variable critter, variable type) begin
   variable slot;
@@ -16,9 +16,23 @@ end

 #define math_max(x, y)               (x if x > y else y)
 #define math_min(x, y)               (x if x < y else y)
+
+/**
+ * Returns true if x is within range: [from, to]
+ * @arg {any} x
+ * @arg {any} from
+ * @arg {any} to
+ * @ret {bool}
+ */
 #define math_in_range(x, from, to)   (x >= from and x <= to)

-
+/**
+ * Returns: a if val < a, b if val > b, otherwise val.
+ * @arg {any} val
+ * @arg {any} a
+ * @arg {any} b
+ * @ret {any}
+ */
 procedure math_clamp(variable val, variable a, variable b) begin
   variable min, max;
   if (a < b) then begin
@@ -23,7 +23,9 @@ end*/
 end*/

 /**
-   Parses keyboard shortcut definition (key code + optional modifier key) from a string into an integer for later use in other hotkey procedures.
+ * Parses keyboard shortcut definition (key code + optional modifier key) from a string into an integer for later use in other hotkey procedures.
+ * @arg {string} string
+ * @ret {int}
 */
 procedure parse_hotkey(variable string) begin
   variable lst;
@@ -38,7 +40,9 @@ procedure parse_hotkey(variable string) begin
 end

 /**
-   Checks if a given shortcut is currently pressed (see parse_hotkey).
+ * Checks if a given shortcut is currently pressed (see parse_hotkey).
+ * @arg {int} n - hotkey data parsed with *parse_hotkey*
+ * @ret {bool}
 */
 procedure hotkey_pressed(variable n) begin
   if (n < 0x10000) then
@@ -48,7 +52,10 @@ procedure hotkey_pressed(variable n) begin
 end

 /**
-   Checks if a shortcut is currently pressed, given that *key* is already pressed.
+ * Checks if a shortcut is currently pressed, given that *key* is already pressed.
+ * @arg {int} n - hotkey data parsed with *parse_hotkey*
+ * @arg {int} key - DX scancode
+ * @ret {bool}
 */
 procedure hotkey_pressed_now(variable n, variable key) begin
   if (n < 0x10000) then
@@ -66,7 +73,11 @@ procedure hotkey_pressed_now(variable n, variable key) begin
 end

 /**
-   Loads ini section as map of keys and values parsed as integers (0 values will be skipped!)
+ * Loads ini section as map of keys and values parsed as integers (0 values will be skipped!)
+ * @arg {string} file
+ * @arg {string} section
+ * @arg {bool} [fixArray=false] - if true, *fix_array* will be called automatically on resulting array
+ * @ret {map}
 */
 procedure get_ini_section_int_to_int(variable file, variable section, variable fixArray := false) begin
   variable ar, ar2 := temp_array_map, k, v;
@@ -5,23 +5,33 @@
 #include "define_extra.h"

 /**
-   Object name or (null) if it's 0. Helps to avoid crashes when debugging.
+ * Object name or (null) if it's 0. Helps to avoid crashes when debugging.
+ * @arg {ObjectPtr} obj
+ * @ret {string}
 */
 #define obj_name_safe(obj)          (obj_name(obj) if obj else "(null)")

 /**
-   Active weapon of a given *critter* (player or NPC).
+ * Active weapon of a given *critter* (player or NPC).
+ * @arg {ObjectPtr} critter
+ * @ret {ObjectPtr}
 */
 #define get_active_weapon(critter)  critter_inven_obj(critter, (2 - active_hand) if critter == dude_obj else INVEN_TYPE_RIGHT_HAND)

 /**
-   Checks if given *critter* has line-of-fire to the given *obj*.
-   In FO2, regular "line of sight" checks are usually unreliable, due to how scenery flags are configured. So LoF checks are a good alternative.
+ * Checks if given *critter* has line-of-fire to the given *target*.
+ * In FO2, regular "line of sight" checks are usually unreliable, due to how scenery flags are configured. So LoF checks are a good alternative.
+ * @arg {ObjectPtr} critter
+ * @arg {ObjectPtr} target
+ * @ret {bool}
 */
 #define obj_has_lof_to_obj(critter, target)           (obj_blocking_line(critter, tile_num(target), BLOCKING_TYPE_SHOOT) == target)

 /**
-   Checks if given *critter* has line-of-fire to *target* and also passes a normal perception check (can "hear" it).
+ * Checks if given *critter* has line-of-fire to *target* and also passes a normal perception check (can "hear" it).
+ * @arg {ObjectPtr} critter
+ * @arg {ObjectPtr} target
+ * @ret {bool}
 */
 #define obj_can_hear_and_shoot_obj(critter, target)   (obj_can_hear_obj(critter, target) and obj_has_lof_to_obj(critter, target))

@@ -12,29 +12,48 @@
 #include "sfall.h"

 /**
-   Checks if *str* contains *sub* as part of it anywhere in the string. 
+ * Checks if *str* contains *sub* as part of it anywhere in the string. 
+ * @arg {string} str
+ * @arg {string} sub
+ * @ret {bool}
 */
 #define string_contains(str, sub)      (string_find(str, sub) != -1)

 /**
-   Checks if *str* contains *sub* at the beginning of the string. 
+ * Checks if *str* contains *sub* at the beginning of the string.
+ * @arg {string} str
+ * @arg {string} sub
+ * @ret {bool}
 */
 #define string_starts_with(str, sub)   (string_find(str, sub) == 0)

 /**
-   Same as *string_format*, but takes parameters from a given list array.
+ * Same as *string_format*, but takes parameters from a given list array.
+ * @arg {string} fmt
+ * @arg {list} arr
+ * @ret {string}
 */
 #define string_format_array(fmt, arr)  sprintf_array(fmt, arr)

 /**
-   Replaces all occurances of *search* in *str* with *replace* string.
+ * Replaces all occurances of *search* in *str* with *replace* string.
+ * @arg {string} str
+ * @arg {string} search
+ * @arg {string} replace
+ * @ret {string}
 */
 #define string_replace(str, search, replace)    (string_join(string_split(str, search), replace))

+/**
+ * @deprecated - use *string_format* instead
+ */
 #define sprintf2(fmt, arg1, arg2)      string_format2(fmt, arg1, arg2)

 /**
-   Joins *array* of strings into a new string using *join* as delimeter.
+ * Joins *array* of strings into a new string using *join* as delimeter.
+ * @arg {list} array
+ * @arg {string} join
+ * @ret {string}
 */
 procedure string_join(variable array, variable join) begin
   variable str, i, len;
@@ -50,7 +69,10 @@ procedure string_join(variable array, variable join) begin
 end

 /**
-   Like *sprintf* but takes parameters from a given list array.
+ * Like *sprintf* but takes parameters from a given list array.
+ * @arg {string} str
+ * @arg {list} args
+ * @ret {string}
 */
 procedure sprintf_array(variable str, variable args) begin
   variable split, len, i, j;
@@ -111,7 +133,10 @@ procedure string_get_tokens(variable str, variable delim) begin
 end

 /**
-   Creates a string by repeating *str* *count* times.
+ * Creates a string by repeating *str* *count* times.
+ * @arg {string} str
+ * @arg {int} count
+ * @ret {string}
 */
 procedure string_repeat(variable str, variable count) begin
   variable out := "", i := 0;
@@ -125,6 +150,9 @@ end
 /**
 * The same as sfall string_split, but returns array of integers instead
 * Useful in cunjunction with is_in_array()
+ * @arg {string} str
+ * @arg {string} split
+ * @ret {list}
 */
 procedure string_split_ints(variable str, variable split) begin
   variable n := 0;
@@ -147,6 +175,8 @@ end

 /**
 * *atoi* proc wrapper, for use as a delegate.
+ * @arg {string} str
+ * @ret {int}
 */
 procedure string_to_int(variable str) begin
   return atoi(str);
@@ -154,6 +184,8 @@ end

 /**
 * *atof* proc wrapper, for use as a delegate.
+ * @arg {string} str
+ * @ret {float}
 */
 procedure string_to_float(variable str) begin
   return atof(str);
@@ -161,6 +193,8 @@ end

 /**
 * Converts any value to a string, for use as a delegate.
+ * @arg {any} val
+ * @ret {string}
 */
 procedure to_string(variable val) begin
   return ""+val;