Add useful comments to most header lib procs and macros

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