Add useful comments to most header lib procs and macros

artifacts/scripting/headers/lib.arrays.h

@@ -71,13 +71,7 @@ procedure array_sum(variable arr);
 // returns random value from array
 procedure array_random_value(variable arr);
 
-/**
- * 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
- * returns arr
- */
+
 procedure array_fill(variable arr, variable pos, variable count, variable value);
 
 /**
@@ -118,14 +112,10 @@ procedure array_transform_kv(variable arr, variable keyFunc, variable valueFunc)
    DEPRECATED, use collections instead
  */
 
-/**
- * Adds new empty place for a new block into array. Returns index of new block that was "created".
- */
+// Adds new empty place for a new block into array. Returns index of new block that was "created".
 procedure add_array_block(variable arr, variable blocksize);
 
-/**
- * Removes a block from an array by index
- */
+// Removes a block from an array by index.
 procedure remove_array_block(variable arr, variable blocksize, variable index);
 
 /**
@@ -133,6 +123,7 @@ procedure remove_array_block(variable arr, variable blocksize, variable index);
  */
 #define debug_array_str(arr)     debug_array_str_deep(arr, 1)
 
+// Prints contents of a given array to main message window, for debugging purposes.
 #define display_array(arr)       display_msg(debug_array_str(arr))
 
 
@@ -152,7 +143,9 @@ procedure load_collection(variable name);
 // the difference between this and load_create_array is that array itself might not be saved (but sfall global is always saved)
 //procedure sfall_global_array(variable global, variable size);
 
-
+/**
+ * Loads a "saved" array. If it doesn't exist, creates it (with a given size).
+ */
 #define load_create_array_map(name)    (load_create_array(name, -1))
 #define get_saved_array_new_map(name)    (get_saved_array_new(name, -1))
 //#define sfall_global_array_map(name)    (sfall_global_array(name, -1))
@@ -160,8 +153,6 @@ procedure load_collection(variable name);
 
 // IMPLEMENTATION
 
-#define ARRAY_SET_BLOCK_SIZE  (10)
-
 procedure map_contains_key(variable arrayMap, variable key) begin
    variable i;
    for (i := 0; i < len_array(arrayMap); i++) begin
@@ -171,7 +162,7 @@ procedure map_contains_key(variable arrayMap, variable key) begin
 end
 
 /**
- * Returns first index of zero value
+ * Returns first index of zero value in a list array.
  */
 procedure get_empty_array_index(variable array) begin
    variable zero := false;
@@ -186,7 +177,9 @@ procedure get_empty_array_index(variable array) begin
    return i;
 end
 
-// push new item at the end of array
+/**
+ * Pushes new item to the end of a list array.
+ */
 procedure array_push(variable array, variable item) begin
    variable n;
    n := len_array(array);
@@ -195,7 +188,9 @@ procedure array_push(variable array, variable item) begin
    return array;
 end
 
-// remove last item from array and returns it's value
+/**
+ * Removes last item from list array (reducing it's size by 1) and returns it's value.
+ */
 procedure array_pop(variable array) begin
    variable n, ret;
    n := len_array(array) - 1;
@@ -207,6 +202,9 @@ procedure array_pop(variable array) begin
    return 0;
 end
 
+/** 
+ * Returns a temp list of keys from a given map array.
+ */
 procedure array_keys(variable array) begin
    variable tmp, i, len;
    len := len_array(array);
@@ -219,6 +217,9 @@ procedure array_keys(variable array) begin
    return tmp;
 end
 
+/**
+ * Returns a temp list of values from a given map array.
+ */
 procedure array_values(variable array) begin
    variable v, tmp, i, len;
    len := len_array(array);
@@ -231,11 +232,17 @@ procedure array_values(variable array) begin
    return tmp;
 end
 
+/**
+ * Sets given array as permanent and returns it.
+ */
 procedure array_fixed(variable array) begin
    fix_array(array);
    return array;
 end
 
+/**
+ * Returns a slice of a given list array as a new temp array.
+ */
 procedure array_slice(variable array, variable index, variable count) begin
    variable tmp, i, n;
    n := len_array(array);
@@ -253,6 +260,9 @@ procedure array_slice(variable array, variable index, variable count) begin
    return tmp;
 end
 
+/**
+ * Removes a slice of given list array.
+ */
 procedure array_cut(variable array, variable index, variable count) begin
    variable i, n;
    n := len_array(array);
@@ -270,6 +280,9 @@ procedure array_cut(variable array, variable index, variable count) begin
    return array;
 end
 
+/**
+ * Removes all values in arr1 that also present in arr2.
+ */
 procedure array_diff(variable arr1, variable arr2) begin
    variable i, v, isMap;
    isMap := array_is_map(arr1);
@@ -312,6 +325,9 @@ procedure clone_array(variable array) begin
    return new;
 end
 
+/**
+ * Compares two arrays (list or map) and returns true if they have identical values in the same order.
+ */
 procedure arrays_equal(variable arr1, variable arr2) begin
    variable n, i, k1, k2;
    if (array_is_map(arr1) != array_is_map(arr2)) then
@@ -332,7 +348,9 @@ procedure arrays_equal(variable arr1, variable arr2) begin
    return true;
 end
 
-// returns maximum element in array
+/**
+ * Returns maximum element in array.
+ */
 procedure array_max(variable arr) begin
    variable v, max;
    max := 0;
@@ -343,7 +361,9 @@ procedure array_max(variable arr) begin
    return max;
 end
 
-// returns minimum element in array
+/**
+ * Returns minimum element in array.
+ */
 procedure array_min(variable arr) begin
    variable v, min;
    min := 0;
@@ -354,7 +374,9 @@ procedure array_min(variable arr) begin
    return min;
 end
 
-// returns sum of array elements (or concatenated string, if elements are strings)
+/**
+ * Returns sum of array elements (or concatenated string, if elements are strings).
+ */
 procedure array_sum(variable arr) begin
    variable v, sum;
    sum := 0;
@@ -364,11 +386,20 @@ procedure array_sum(variable arr) begin
    return sum;
 end
 
+/**
+ * Returns a random value from a given list array.
+ */
 procedure array_random_value(variable arr) begin
    return get_array(arr, array_key(arr, random(0, len_array(arr) - 1)));
 end
 
 
+#define ARRAY_SET_BLOCK_SIZE  (10)
+
+/**
+ * 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.
+ */
 procedure add_array_set(variable array, variable item) begin
    variable i := 0;
    variable len;
@@ -390,9 +421,14 @@ procedure add_array_set(variable array, variable item) begin
          resize_array(array, len + ARRAY_SET_BLOCK_SIZE);
       end
       set_array(array, i, item);
+      return true;
    end
+   return false;
 end
 
+/**
+ * Remove value from a set (list array). Returns true if item was actually found and removed.
+ */
 procedure remove_array_set(variable array, variable item) begin
    variable i := 0;
    variable len;
@@ -411,10 +447,18 @@ procedure remove_array_set(variable array, variable item) begin
    if (found_at != -1) then begin
       array[found_at] := array[i - 1];
       array[i - 1] := 0;
+      return true;
    end
+   return false;
 end
 
-// Creates a new array filled from a given array by transforming each value using given procedure name.
+#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.
+ */
 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);
    foreach (k: v in arr) begin
@@ -423,7 +467,12 @@ procedure array_transform(variable arr, variable valueFunc) begin
    return retArr;
 end
 
-// Create a new temp array filled from a given array by transforming each key and value using given procedure name.
+/**
+   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.
+ */
 procedure array_transform_kv(variable arr, variable keyFunc, variable valueFunc) begin
    variable k, v, retArr := temp_array_map;
    foreach (k: v in arr) begin
@@ -432,6 +481,9 @@ procedure array_transform_kv(variable arr, variable keyFunc, variable valueFunc)
    return retArr;
 end
 
+/**
+ * Converts given array into a new map where keys are array values and all values are 1.
+ */
 procedure array_to_set(variable arr) begin
    variable v, retArr := temp_array_map;
    foreach (v in arr) begin
@@ -491,6 +543,14 @@ procedure remove_array_block(variable arr, variable blocksize, variable index) b
    end
 end
 
+#undef ARRAY_EMPTY_INDEX
+
+/**
+ * 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;
+ */
 procedure array_fill(variable arr, variable pos, variable count, variable value) begin
    variable i := 0;
    if (count == -1 or (pos + count > len_array(arr))) then count := len_array(arr) - pos; // this should prevent write to illegal offsets
@@ -501,6 +561,9 @@ procedure array_fill(variable arr, variable pos, variable count, variable value)
    return arr;
 end
 
+/**
+ * Adds all the values of the second array to the first array.
+ */
 procedure array_append(variable arr1, variable arr2) begin
    variable arr1_len;
    if (array_is_map(arr1)) then begin
@@ -516,7 +579,9 @@ procedure array_append(variable arr1, variable arr2) begin
    return arr1;
 end
 
-// Loads a "saved" array. If it doesn't exist, creates it (with a given size).
+/**
+ * Loads a "saved" array. If it doesn't exist, creates it (with a given size).
+ */
 procedure load_create_array(variable name, variable size) begin
    variable arr;
    arr := load_array(name);
@@ -527,7 +592,9 @@ procedure load_create_array(variable name, variable size) begin
    return arr;
 end
 
-// Creates and returns a new "saved" array. If array already existed with this name, frees it.
+/**
+ * Creates and returns a new "saved" array. If array already existed with this name, frees it.
+ */
 procedure get_saved_array_new(variable name, variable size) begin
    variable arr;
    arr := load_array(name);
@@ -540,6 +607,9 @@ end
 
 #define _ITEM_NAME(colname, itemkey)      ""+colname+"."+itemkey
 
+/**
+ * A collection is a 2-level-deep saved array (a saved array containing other saved arrays as values).
+ */
 procedure save_collection(variable name, variable arr) begin
    variable k, v, keys, oldKeys;
    keys := array_keys(arr);
@@ -570,54 +640,13 @@ end
 #undef _ITEM_NAME
 
 
-/* NOT SAFE
-procedure sfall_global_array(variable global, variable size) begin
-   variable ar;
-   ar := get_sfall_global_int(global);
-   if (ar == 0) then begin
-      ar := create_array(size, 0); // persistent array, but not saved
-      set_sfall_global(global, ar);
-   end
-   return ar;
-end*/
-
-/*
-DEPRECATED code, just for reference, don't use
-
-procedure get_sfall_global_array(variable global_id, variable elemcount, variable elemsize) begin
-   variable ar;
-   ar := get_sfall_global_int(global_id);
-   if (ar == 0) then begin
-      ar := create_array(elemcount, elemsize);
-      set_sfall_global(global_id, ar);
-   end
-   return ar;
-end
-
-procedure get_sfall_global_array_new(variable global_id, variable elemcount, variable elemsize) begin
-   variable ar;
-   variable i;
-   variable it;
-   ar := get_sfall_global_int(global_id);
-   if (ar == 0) then begin
-      ar := create_array(elemcount, elemsize);
-      set_sfall_global(global_id, ar);
-   end else begin
-      i := 0;
-      resize_array(ar, elemcount);
-      while (i < len_array(ar)) do begin
-         ar[i] := 0;
-         i++;
-      end
-   end
-   return ar;
-end
-*/
-
 /**
   Different utility functions...
 */
 
+/**
+ * Prints array contents with a given level of recursion.
+ */
 procedure debug_array_str_deep(variable arr, variable levels) begin
 #define _newline if (levels > 1) then s += "\n";
 #define _indent ii := 0; while (ii < levels - 1) do begin s += "   "; ii++; end
@@ -659,6 +688,7 @@ procedure debug_array_str_deep(variable arr, variable levels) begin
 #undef _value
 end
 
+// NUKES all saved arrays. Don't use in production code.
 procedure _PURGE_all_saved_arrays begin
    variable saved, key;
    saved := list_saved_arrays;

artifacts/scripting/headers/lib.inven.h

@@ -7,8 +7,8 @@
 #define PID_BOTTLE_CAPS                     (41)
 
 /**
-  Inventory contents as temp array to be used in foreach
-*/
+ * Inventory contents as temp array to be used in foreach
+ */
 procedure inven_as_array(variable critter) begin
    variable i:=0, list;
    list := temp_array(100, 4);
@@ -22,7 +22,9 @@ procedure inven_as_array(variable critter) begin
    return list;
 end
 
-
+/**
+ * Adds quantity of itemPid to invenObj.
+ */
 procedure add_items_pid(variable invenObj, variable itemPid, variable quantity) begin
    variable item;
    item := create_object(itemPid, 0, 0);
@@ -30,13 +32,18 @@ procedure add_items_pid(variable invenObj, variable itemPid, variable quantity)
    return item;
 end
 
-// aliases:
+/**
+ * Adds 1 item of a given pid to obj.
+ */
 #define add_item_pid(obj, pid)            add_items_pid(obj, pid, 1)
 
 #ifndef critter_wearing_armor
 #define critter_wearing_armor(x)            (obj_item_subtype(critter_inven_obj(x,INVEN_TYPE_WORN)) == item_type_armor)
 #endif
 
+/**
+ * Makes critter remove his armor and put it back to his inventory.
+ */
 procedure unwield_armor(variable critter) begin
    variable armor;
    if (not(critter)) then return;
@@ -47,6 +54,14 @@ procedure unwield_armor(variable critter) begin
    end
 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.
+ */
 procedure remove_items_pid(variable invenObj, variable itemPid, variable quantity) begin
    variable begin
       item;
@@ -74,8 +89,12 @@ procedure remove_items_pid(variable invenObj, variable itemPid, variable quantit
    return toRemoveQty;
 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.
+ */
 procedure remove_item_obj(variable invenObj, variable item) begin
-   if (obj_type(invenObj) == 1) then begin
+   if (obj_type(invenObj) == OBJ_TYPE_CRITTER) then begin
       if (critter_inven_obj(invenObj,INVEN_TYPE_WORN) == item) then begin
          call unwield_armor(invenObj);
       end else if ((critter_inven_obj(invenObj, INVEN_TYPE_LEFT_HAND) == item) or (critter_inven_obj(invenObj, INVEN_TYPE_RIGHT_HAND) == item)) then begin
@@ -86,29 +105,38 @@ procedure remove_item_obj(variable invenObj, variable item) begin
    destroy_object(item);
 end
 
-// aliases:
+/**
+   Remove one item of a given *pid* from *obj* inventory.
+ */
 #define remove_item_pid(obj, pid)            remove_items_pid(obj, pid, 1)
+
+/**
+   Remove all items of a given *pid* from *obj* inventory.
+ */
 #define remove_all_items_pid(obj, pid)       remove_items_pid(obj, pid, -1)
 
 /**
- Set item quantity in inventory, by item pid
+   Ensures a given *quantity* of *itemPid* in *invenObj* inventory, adding or removing items as necessary.
  */
-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);
-      add_mult_objs_to_inven(invenobj, obj, quantity - count);
+      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.
+ */
 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;
    inv := inven_as_array(critter);
@@ -135,6 +163,9 @@ procedure reduce_merchant_loot(variable critter, variable moneyPercent, variable
    end
 end
 
+/**
+   Returns item in one of *critter*'s hand slots using given attack type.
+ */
 procedure item_by_attack_type(variable critter, variable type) begin
    variable slot;
    if (type > 3 and type != ATKTYPE_LWEP_RELOAD and type != ATKTYPE_RWEP_RELOAD) then

artifacts/scripting/headers/lib.misc.h

@@ -22,7 +22,9 @@ end*/
    return var;
 end*/
 
-// Parse keyboard shortcut definition
+/**
+   Parses keyboard shortcut definition (key code + optional modifier key) from a string into an integer for later use in other hotkey procedures.
+ */
 procedure parse_hotkey(variable string) begin
    variable lst;
    variable n;
@@ -35,7 +37,9 @@ procedure parse_hotkey(variable string) begin
    return n;
 end
 
-// Check if shortcut is pressed
+/**
+   Checks if a given shortcut is currently pressed (see parse_hotkey).
+ */
 procedure hotkey_pressed(variable n) begin
    if (n < 0x10000) then
       return key_pressed(n);
@@ -43,7 +47,9 @@ procedure hotkey_pressed(variable n) begin
       return key_pressed(n bwand 0xFFFF) and key_pressed((n bwand 0xFFFF0000) / 0x10000);
 end
 
-// same as above, but suited for hs_keypress hook when keycode is already known
+/**
+   Checks if a shortcut is currently pressed, given that *key* is already pressed.
+ */
 procedure hotkey_pressed_now(variable n, variable key) begin
    if (n < 0x10000) then
       return key == n;
@@ -59,7 +65,9 @@ procedure hotkey_pressed_now(variable n, variable key) begin
    end
 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!)
+ */
 procedure get_ini_section_int_to_int(variable file, variable section, variable fixArray := false) begin
    variable ar, ar2 := temp_array_map, k, v;
    ar := get_ini_section(file, section);

artifacts/scripting/headers/lib.obj.h

@@ -4,9 +4,25 @@
 #include "define_lite.h"
 #include "define_extra.h"
 
+/**
+   Object name or (null) if it's 0. Helps to avoid crashes when debugging.
+ */
 #define obj_name_safe(obj)          (obj_name(obj) if obj else "(null)")
+
+/**
+   Active weapon of a given *critter* (player or NPC).
+ */
 #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.
+ */
 #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).
+ */
 #define obj_can_hear_and_shoot_obj(critter, target)   (obj_can_hear_obj(critter, target) and obj_has_lof_to_obj(critter, target))
 
 #endif

artifacts/scripting/headers/lib.strings.h

@@ -11,15 +11,30 @@
 
 #include "sfall.h"
 
+/**
+   Checks if *str* contains *sub* as part of it anywhere in the string. 
+ */
 #define string_contains(str, sub)      (string_find(str, sub) != -1)
-#define string_starts_with(str, sub)   (substr(str, 0, strlen(sub)) == sub)
+
+/**
+   Checks if *str* contains *sub* at the beginning of the string. 
+ */
+#define string_starts_with(str, sub)   (string_find(str, sub) == 0)
+
+/**
+   Same as *string_format*, but takes parameters from a given list array.
+ */
 #define string_format_array(fmt, arr)  sprintf_array(fmt, arr)
-// Replaces all occurances of substring in a string with another substring
+
+/**
+   Replaces all occurances of *search* in *str* with *replace* string.
+ */
 #define string_replace(str, search, replace)    (string_join(string_split(str, search), replace))
+
 #define sprintf2(fmt, arg1, arg2)      string_format2(fmt, arg1, arg2)
 
 /**
- * Join array of strings using delimeter
+   Joins *array* of strings into a new string using *join* as delimeter.
  */
 procedure string_join(variable array, variable join) begin
    variable str, i, len;
@@ -35,7 +50,7 @@ procedure string_join(variable array, variable join) begin
 end
 
 /**
- * sprintf with unlimited number of arguments
+   Like *sprintf* but takes parameters from a given list array.
  */
 procedure sprintf_array(variable str, variable args) begin
    variable split, len, i, j;
@@ -72,9 +87,7 @@ variable lst, n;
    return string_len(str) - (string_len(lst[n-1]) + string_len(substr));
 end*/
 
-/**
- * Basically the same as string_split, but delim is of type char instead of string
- */
+// UNFINISHED, don't use!
 procedure string_get_tokens(variable str, variable delim) begin
    variable lst, line, token, maxlen, len, count;
    count := 1;
@@ -97,6 +110,9 @@ procedure string_get_tokens(variable str, variable delim) begin
    return count;
 end
 
+/**
+   Creates a string by repeating *str* *count* times.
+ */
 procedure string_repeat(variable str, variable count) begin
    variable out := "", i := 0;
    while (i < count) do begin
@@ -129,17 +145,23 @@ procedure string_split_ints(variable str, variable split) begin
    return result;
 end
 
-// atoi proc wrapper, for use as callback
+/**
+ * *atoi* proc wrapper, for use as a delegate.
+ */
 procedure string_to_int(variable str) begin
    return atoi(str);
 end
 
-// atof proc wrapper, for use as callback
+/**
+ * *atof* proc wrapper, for use as a delegate.
+ */
 procedure string_to_float(variable str) begin
    return atof(str);
 end
 
-// converts any value to a string, for use as callback
+/**
+ * Converts any value to a string, for use as a delegate.
+ */
 procedure to_string(variable val) begin
    return ""+val;
 end