an obscene amount of documentation

johnny.cfg

@@ -1,15 +1,14 @@
 Game Maker 8.2 Core
-source\gm82core.gml
 source\accelerators.gml
 source\data_structures.gml
 source\drawing.gml
-source\instances.gml
-source\math.gml
-source\strings.gml
-source\system.gml
 source\gm82core.c
 source\hrt.c
+source\instances.gml
 source\lovey01.c
 source\math.c
-source\windows.c
-source\terrible_gm8_hacking.c
+source\math.gml
+source\strings.gml
+source\system.gml
+source\terrible_gm8_hacking.c
+source\windows.c

source/accelerators.gml

@@ -1,6 +1,7 @@
 #define alarm_get
     ///alarm_get(numb)
     //numb: integer - alarm index
+    //returns: frame count
     //Similar to Studio function. Gets the value of an instance alarm.
 
     return alarm[argument0]
@@ -9,13 +10,16 @@
 #define alarm_set
     ///alarm_set(numb,steps)
     //numb: integer - alarm index
+    //steps: integer - frame count
+    //returns: nothing
     //Similar to Studio function. Sets the value of an instance alarm.
 
     alarm[argument0]=argument1
 
 
 #define animation_stop
     ///animation_stop()
+    //returns: nothing
     //Stops the instance's animation on the last frame.
     //Particularly useful for Animation end events.
 
@@ -26,27 +30,31 @@
 #define event_alarm
     ///event_alarm(numb)
     //numb: integer - alarm index
+    //returns: nothing
     //Shortcut function. Executes the actions in the Alarm event indicated.
 
     event_perform(ev_alarm,argument0)
 
 
 #define event_beginstep
     ///event_beginstep()
+    //returns: nothing
     //Shortcut function. Executes the actions in the Begin Step event.
 
     event_perform(ev_step,ev_step_begin)
 
 
 #define event_draw
     ///event_draw()
+    //returns: nothing
     //Shortcut function. Executes the actions in the Draw event.
 
     event_perform(ev_draw,0)
 
 
 #define event_endstep
     ///event_endstep()
+    //returns: nothing
     //Shortcut function. Executes the actions in the End Step event.
 
     event_perform(ev_step,ev_step_end)
@@ -55,53 +63,60 @@
 #define event_inherit_object
     ///event_inherit_object(object)
     //object: object - object to inherit
+    //returns: nothing
     //Executes the same event from a different object.
 
     event_perform_object(argument0,event_type,event_number)
 
 
 #define event_step
     ///event_step()
+    //returns: nothing
     //Shortcut function. Executes the actions in the Step event.
 
     event_perform(ev_step,ev_step_normal)
 
 
 #define event_trigger
     ///event_trigger(trig)
-    //trig: trigger - trigger constant
+    //trig: trigger constant - trigger event to fire
+    //returns: nothing
     //Shortcut function. Executes a trigger event.
 
     event_perform(ev_trigger,argument0)
 
 
 #define object_is_child_of
     ///object_is_child_of(object)
-    //object: object - object to check
+    //object: object to check
+    //returns: bool
     //Checks if the instance is a child of or the object itself.
 
     return object_index==argument0 || object_is_ancestor(object_index,argument0)
 
 
 #define object_other_is_child_of
     ///object_other_is_child_of(object)
-    //object: object - object to check
+    //object: object to check
+    //returns: bool
     //Checks if the other instance is a child of or the object itself.
 
     return other.object_index==argument0 || object_is_ancestor(other.object_index,argument0)
 
 
 #define pick
-    ///pick(which,opt1,opt2,...)
+    ///pick(which,opt1,opt2,...) -> option
     //which: integer - which option to return
+    //returns: option picked
     //Returns one of the arguments depending on the first argument.
 
     return argument[(argument[0] mod (argument_count-1))+1]
 
 
 #define tile_find_anywhere
-    ///tile_find_anywhere(x,y)
+    ///tile_find_anywhere(x,y) -> tile
     //x,y: vector - coordinate to check
+    //returns: tile id
     //Finds a tile at the coordinate, regardless of layer depth.
 
     var __t;

source/data_structures.gml

@@ -1,8 +1,13 @@
 #define dslist
-    ///dslist(list,pos,val) -> value
-    ///dslist(list,pos) -> value
-    ///dslist(list) -> string
-    ///dslist() -> list
+    ///dslist(list,[pos,[val]])
+    //list: ds list index
+    //pos: list position to operate
+    //val: value to store
+    //call with 3 arguments: sets value, returns value
+    //call with 2 arguments: returns found value at pos
+    //call with 1 argument: returns string of list
+    //call with 0 arguments: returns new list
+    //List accelerator function. Performs different actions depending on arguments.
     var __i,__s,__str;
 
     if (argument_count==0) {
@@ -37,10 +42,15 @@
 
 
 #define dsmap
-    ///dsmap(map,key,value) -> value
-    ///dsmap(map,key) -> value
-    ///dsmap(map) -> string
-    ///dsmap() -> map
+    ///dsmap(map,[key,[value]])
+    //map: ds map index
+    //key: map key to operate on
+    //val: value to store
+    //call with 3 arguments: sets key to value, returns value
+    //call with 2 arguments: returns found value in key
+    //call with 1 argument: returns string of map
+    //call with 0 arguments: returns new map
+    //Map accelerator function. Performs different actions depending on arguments.
     var __key,__str,__val;
 
     if (argument_count==0) {
@@ -77,6 +87,9 @@
 
 #define ds_list_equal
     ///ds_list_equal(list1,list2)
+    //list1, list2: ds list indexes
+    //returns: bool
+    //Compares both lists item by item, and returns whether they're identical.
     var __i,__s;
 
     __s=ds_list_size(argument0)
@@ -93,7 +106,9 @@
 
 #define ds_map_add_copy
     ///ds_map_add_copy(src,dest)
-    //copies all keys from src to dest without clearing dest
+    //src, dest: ds map indexes
+    //returns: nothing
+    //Copies all keys from source map to dest map.
     var __key;__key=ds_map_find_first(argument0)
     repeat (ds_map_size(argument0)) {
         if (ds_map_exists(argument1,__key)) ds_map_replace(argument1,__key,ds_map_find_value(argument0,__key))
@@ -104,17 +119,27 @@
 
 #define ds_map_get
     ///ds_map_get(map,key)
+    //map: ds map index
+    //key: key to get
+    //returns: key value, or "<undefined>"
+    //Studio shim. Returns undefined when the key does not exist.
     if (ds_map_exists(argument0,argument1)) return ds_map_find_value(argument0,argument1)
     return undefined
 
 
 #define ds_map_read_ini
     ///ds_map_read_ini(map,filename)
+    //map: ds map index
+    //filename: string, file to load
+    //returns: number of keys loaded
+    //Reads an ini file into a dsmap. Section names are prepended to each key.
     var __map,__f,__section,__str,__p;
 
     if (file_exists(argument1)) {
         __map=argument0
 
+        ds_map_clear(__map)
+
         __f=file_text_open_read(argument1)
         __section=""
         while (!file_text_eof(__f)) {            
@@ -131,21 +156,27 @@
         }   
         file_text_close(__f)
 
-        return 1
+        return ds_map_size(__map)
     }
 
     return 0
 
 
 #define ds_map_read_ini_string
     ///ds_map_read_ini_string(map,string)
+    //map: ds map index
+    //string: string containing ini-like data
+    //returns: number of keys loaded
+    //Reads an ini string into a dsmap. Section names are prepended to each key.
     var __map,__lf,__section,__str,__p;
 
     __map=argument0
     __str=argument1
     if (string_pos(chr($0d)+chr($0a),__str)) __lf=chr($0d)+chr($0a)
     else __lf=chr($0a)
 
+    ds_map_clear(__map)
+
     __section=""
     repeat (string_token_start(__str,__lf)) {            
         __str=string_token_next()
@@ -157,19 +188,28 @@
                 ds_map_add(__map,__section+string_copy(__str,1,__p-1),string_delete(__str,1,__p))
             }            
         }
-    }   
-
-    return 0
+    }
+    
+    return ds_map_size(__map)
 
 
 #define ds_map_set
     ///ds_map_set(map,key,value)
+    //map: ds map index
+    //key: key to operate on
+    //value: value to store
+    //returns: value stored
+    //Replaces or creates a key in a dsmap. Ensures no duplicate keys.
     if (ds_map_exists(argument0,argument1)) ds_map_replace(argument0,argument1,argument2)
     else ds_map_add(argument0,argument1,argument2)
+    return argument2
 
 
 #define is_undefined
     ///is_undefined(val)
+    //val - value to check
+    //returns: bool
+    //Studio shim. checks the value against the 'undefined' constant.
     return string(argument0)==undefined
 //
 //

source/drawing.gml

@@ -1,5 +1,12 @@
 #define draw_background_tiled_extra
     ///draw_background_tiled_extra(back,x,y,xscale,yscale,angle,color,alpha,hrepeats,vrepeats)
+    //back: background index
+    //x,y: origin point for drawing
+    //xscale,yscale,angle: image transform
+    //color,alpha: blend for drawing
+    //hrepeats,vrepeats: number of repetitions. use 0 for infinite.
+    //returns: nothing
+    //Faster version of draw_background_tiled with more options.
 
     var __bg,__dx,__dy,__xs,__ys,__angle,__color,__alpha,__hrep,__vrep;
 
@@ -73,6 +80,8 @@
 
 #define draw_reset
     ///draw_reset()
+    //returns: nothing
+    //Resets the draw color to white, alpha to 1, and text align to left/top.
     draw_set_color($ffffff)
     draw_set_alpha(1)
     draw_set_halign(0)
@@ -81,36 +90,56 @@
 
 #define draw_self_as
     ///draw_self_as(sprite,[image])
+    //sprite: sprite index
+    //image: sprite frame
+    //returns: nothing
+    //Draws the instance using a different sprite.
     var __img;__img=-1
     if (argument_count>1) __img=floor(argument1)
     draw_sprite_ext(argument0,__img,x,y,image_xscale,image_yscale,image_angle,image_blend,image_alpha)
 
 
 #define draw_self_floored
     ///draw_self_floored()
+    //returns: nothing
+    //Draws the instance at a floored coordinate.
     draw_sprite_ext(sprite_index,-1,floor(x),floor(y),image_xscale,image_yscale,image_angle,image_blend,image_alpha)
 
 
 #define draw_set1
     ///draw_set1(color,alpha)
+    //color,alpha: blend to use
+    //returns: nothing
+    //Sets color and alpha at once.
     draw_set_color(argument0)
     draw_set_alpha(argument1)
 
 
 #define draw_set2
     ///draw_set2(halign,valign)
+    //halign,valign: font align constants (fa_)
+    //returns: nothing
+    //Sets both text align options at once.
     draw_set_halign(argument0)
     draw_set_valign(argument1)
 
 
 #define draw_set_rgba
     ///draw_set_rgba(r,g,b,a)
+    //r,g,b: integer color values 0-255
+    //a: float alpha value 0-1
+    //returns: nothing
+    //Sets the draw color using separate RGBA values.
     draw_set_color(make_color_rgb(argument0,argument1,argument2))
     draw_set_alpha(argument3)
 
 
 #define draw_sprite_ext_fixed
     ///draw_sprite_ext_fixed(sprite,image,x,y,xscale,yscale,angle,color,alpha)
+    //arguments: same as draw_sprite_ext
+    //returns: nothing
+    //Version of draw_sprite_ext that accounts for the half-pixel offset.
+    //Good for drawing even-width sprites that rotate.
     draw_sprite_ext(
         argument0,floor(argument1),
         argument2+lengthdir_x(0.5,argument6)+lengthdir_x(0.5,argument6-90),
@@ -121,11 +150,19 @@
 
 #define draw_text_1color
     ///draw_text_1color(x,y,string,color,alpha)
+    //arguments: same as draw_text_color but with 1 color.
+    //returns: nothing
+    //Helper function that only takes 1 color argument.
     draw_text_color(argument0,argument1,argument2,argument3,argument3,argument3,argument3,argument4)
 
 
 #define draw_rect
-    ///draw_rect(x,y,w,h,[color,alpha,angle])
+    ///draw_rect(x,y,w,h,[color,[alpha,[angle]]])
+    //x,y,w,h: rectangle position and size
+    //color,alpha: blend to use (filled only)
+    //angle: rotation around x,y coordinate
+    //returns: nothing
+    //draws a filled rectangle using a fast sprite method.
     var __color,__alpha,__rot;
 
     __color=$ffffff