Start event macro comment updates

1 files changed, 180 insertions, 163 deletions

diff --git a/asm/macros/event.inc b/asm/macros/event.inc
index 27a439725..01a7889fe 100644
--- a/asm/macros/event.inc
+++ b/asm/macros/event.inc
@@ -56,20 +56,20 @@
 	STD_OBTAIN_DECORATION = 7
 	STD_REGISTER_MATCH_CALL = 8
 
-	@ Calls the standard function at index function.
+	@ Executes the script in gStdScripts at index function.
 	.macro callstd function:req
 	.byte 0x09
 	.byte \function
 	.endm
 
-	@ If the result of the last comparison matches condition (see Comparison operators), jumps to the standard function at index function.
+	@ If the result of the last comparison matches condition (see Comparison operators), jumps to the script in gStdScripts at index function.
 	.macro gotostd_if condition:req, function:req
 	.byte 0x0a
 	.byte \condition
 	.byte \function
 	.endm
 
-	@ If the result of the last comparison matches condition (see Comparison operators), calls the standard function at index function.
+	@ If the result of the last comparison matches condition (see Comparison operators), calls the script in gStdScripts at index function.
 	.macro callstd_if condition:req, function:req
 	.byte 0x0b
 	.byte \condition
@@ -120,6 +120,7 @@
 	.4byte \source
 	.endm
 
+	@ TODO
 	@ Not sure. Judging from XSE's description I think it takes the least-significant byte in bank source and writes it to destination.
 	.macro setptrbyte source:req, destination:req
 	.byte 0x13
@@ -233,7 +234,7 @@
 	.endm
 
 	@ Generic compare macro which attempts to deduce argument types based on their values
-	@ Any values between 0x4000 to 0x40FF and 0x8000 to 0x8015 are considered event variable identifiers
+	@ Any values between VARS_START to VARS_END and SPECIAL_VARS_START to SPECIAL_VARS_END are considered event variable identifiers
 	.macro compare var:req, arg:req
 		.if ((\arg >= VARS_START && \arg <= VARS_END) || (\arg >= SPECIAL_VARS_START && \arg <= SPECIAL_VARS_END))
 			compare_var_to_var \var, \arg
@@ -242,39 +243,33 @@
 		.endif
 	.endm
 
-	@ Calls the native C function stored at `func`.
+	@ Calls the native C function stored at func.
 	.macro callnative func:req
 	.byte 0x23
 	.4byte \func
 	.endm
 
-	@ Replaces the script with the function stored at `func`. Execution returns to the bytecode script when func returns TRUE.
+	@ Replaces the script with the function stored at func. Execution returns to the bytecode script when func returns TRUE.
 	.macro gotonative func:req
 	.byte 0x24
 	.4byte \func
 	.endm
 
-	@ Calls a special function; that is, a function designed for use by scripts and listed in a table of pointers.
+	@ Calls a function listed in the table in data/specials.inc.
 	.macro special function:req
 	.byte 0x25
 	.2byte SPECIAL_\function
 	.endm
 
-	@ Calls a special function. That function's output (if any) will be written to the variable you specify.
+	@ Calls a function listed in the table in data/specials.inc.
+	@ That function's output (if any) will be written to the variable specified by 'output'.
 	.macro specialvar output:req, function:req
 	.byte 0x26
 	.2byte \output
 	.2byte SPECIAL_\function
 	.endm
 
-	@ temporary solution
-	.macro specialvar_ output:req, functionId:req
-	.byte 0x26
-	.2byte \output
-	.2byte \functionId
-	.endm
-
-	@ Blocks script execution until a command or ASM code manually unblocks it. Generally used with specific
+	@ Blocks script execution until a command or ASM code manually unblocks it. Generally used with specific 
 	@ commands and specials. If this command runs, and a subsequent command or piece of ASM does not unblock
 	@ state, the script will remain blocked indefinitely (essentially a hang).
 	.macro waitstate
@@ -287,46 +282,46 @@
 	.2byte \frames
 	.endm
 
-	@ Sets a to 1.
-	.macro setflag a:req
+	@ Sets flag to TRUE.
+	.macro setflag flag:req
 	.byte 0x29
-	.2byte \a
+	.2byte \flag
 	.endm
 
-	@ Sets a to 0.
-	.macro clearflag a:req
+	@ Sets flag to FALSE.
+	.macro clearflag flag:req
 	.byte 0x2a
-	.2byte \a
+	.2byte \flag
 	.endm
 
-	@ Compares a to 1.
-	.macro checkflag a:req
+	@ Compares flag to TRUE and stores the result in comparisonResult to be used by goto_if, etc
+	@ See additional _if_unset and _if_set macros
+	.macro checkflag flag:req
 	.byte 0x2b
-	.2byte \a
+	.2byte \flag
 	.endm
 
-	@ Initializes the RTC`s local time offset to the given hour and minute. In FireRed, this command is a nop.
+	@ Initializes the RTC`s local time offset to the given hour and minute.
 	.macro initclock hour:req, minute:req
 	.byte 0x2c
 	.2byte \hour
 	.2byte \minute
 	.endm
 
-	@ Runs time based events. In FireRed, this command is a nop.
+	@ Runs time based events.
 	.macro dotimebasedevents
 	.byte 0x2d
 	.endm
 
-	@ Sets the values of variables 0x8000, 0x8001, and 0x8002 to the current hour, minute, and second. In FRLG,
-	@ this command sets those variables to zero.
+	@ Sets the values of variables VAR_0x8000, VAR_0x8001, and VAR_0x8002 to the current hour, minute, and second.
 	.macro gettime
 	.byte 0x2e
 	.endm
 
-	@ Plays the specified (sound_number) sound. Only one sound may play at a time, with newer ones interrupting older ones.
-	.macro playse sound_number:req
+	@ Plays the specified (song) sound. Only one sound may play at a time, with newer ones interrupting older ones.
+	.macro playse song:req
 	.byte 0x2f
-	.2byte \sound_number
+	.2byte \song
 	.endm
 
 	@ Blocks script execution until the currently-playing sound (triggered by playse) finishes playing.
@@ -335,9 +330,9 @@
 	.endm
 
 	@ Plays the fanfare specified by the song number. If the specified song is not a fanfare it will instead play the first song in sFanfares.
-	.macro playfanfare songNumber:req
+	.macro playfanfare song:req
 	.byte 0x31
-	.2byte \songNumber
+	.2byte \song
 	.endm
 
 	@ Blocks script execution until all currently-playing fanfares finish.
@@ -345,18 +340,18 @@
 	.byte 0x32
 	.endm
 
-	@ Plays the specified (song_number) song. If save_song is TRUE, the
-	@ specified (song_number) will be saved as if savebgm was called with it.
-	.macro playbgm song_number:req, save_song:req
+	@ Plays the specified song. If save_song is TRUE, the
+	@ specified song will be saved as if savebgm was called with it.
+	.macro playbgm song:req, save_song:req
 	.byte 0x33
-	.2byte \song_number
+	.2byte \song
 	.byte \save_song
 	.endm
 
-	@ Saves the specified (song_number) song to be played later.
-	.macro savebgm song_number:req
+	@ Saves the specified song to be played later.
+	.macro savebgm song:req
 	.byte 0x34
-	.2byte \song_number
+	.2byte \song
 	.endm
 
 	@ Crossfades the currently-playing song into the map's default song.
@@ -364,10 +359,10 @@
 	.byte 0x35
 	.endm
 
-	@ Crossfades the currently-playng song into the specified (song_number) song.
-	.macro fadenewbgm song_number:req
+	@ Crossfades the currently-playng song into the specified song.
+	.macro fadenewbgm song:req
 	.byte 0x36
-	.2byte \song_number
+	.2byte \song
 	.endm
 
 	@ Fades out the currently-playing song.
@@ -382,32 +377,37 @@
 	.byte \speed
 	.endm
 
-	@ Sends the player to Warp warp on Map bank.map. If the specified warp is 0xFF,
-	@ then the player will instead be sent to (X, Y) on the map.
-	.macro warp map:req, warp:req, X:req, Y:req
+	@ Warps the player to the specified map.
+	@ The player will warp to the coordinates of the given 'warp'.
+	@ If 'warp' is set to an invalid id (e.g. 255) then the coordinates x/y will be used instead.
+	.macro warp map:req, warp:req, x=0, y=0
 	.byte 0x39
 	map \map
 	.byte \warp
-	.2byte \X
-	.2byte \Y
+	.2byte \x
+	.2byte \y
 	.endm
 
-	@ Clone of warp that does not play a sound effect.
-	.macro warpsilent map:req, warp:req, X:req, Y:req
+	@ Warps the player to the specified map without playing a sound effect.
+	@ The player will warp to the coordinates of the given 'warp'.
+	@ If 'warp' is set to an invalid id (e.g. 255) then the coordinates x/y will be used instead.
+	.macro warpsilent map:req, warp:req, x=0, y=0
 	.byte 0x3a
 	map \map
 	.byte \warp
-	.2byte \X
-	.2byte \Y
+	.2byte \x
+	.2byte \y
 	.endm
 
-	@ Clone of warp that plays a door opening animation before stepping upwards into it.
-	.macro warpdoor map:req, warp:req, X:req, Y:req
+	@ Warps the player to the specified map and plays a door opening animation before stepping upwards into it.
+	@ The player will warp to the coordinates of the given 'warp'.
+	@ If 'warp' is set to an invalid id (e.g. 255) then the coordinates x/y will be used instead.
+	.macro warpdoor map:req, warp:req, x=0, y=0
 	.byte 0x3b
 	map \map
 	.byte \warp
-	.2byte \X
-	.2byte \Y
+	.2byte \x
+	.2byte \y
 	.endm
 
 	@ Warps the player to another map using a hole animation.
@@ -416,57 +416,62 @@
 	map \map
 	.endm
 
-	@ Clone of warp that uses a teleport effect. It is apparently only used in R/S/E.
-	.macro warpteleport map:req, warp:req, X:req, Y:req
+	@ Warps the player to the specified map using a teleport effect.
+	@ The player will warp to the coordinates of the given 'warp'.
+	@ If 'warp' is set to an invalid id (e.g. 255) then the coordinates x/y will be used instead.
+	.macro warpteleport map:req, warp:req, x=0, y=0
 	.byte 0x3d
 	map \map
 	.byte \warp
-	.2byte \X
-	.2byte \Y
+	.2byte \x
+	.2byte \y
 	.endm
 
 	@ Sets the warp destination to be used later.
-	.macro setwarp map:req, warp:req, X:req, Y:req
+	@ The player will warp to the coordinates of the given 'warp'.
+	@ If 'warp' is set to an invalid id (e.g. 255) then the coordinates x/y will be used instead.
+	.macro setwarp map:req, warp:req, x=0, y=0
 	.byte 0x3e
 	map \map
 	.byte \warp
-	.2byte \X
-	.2byte \Y
+	.2byte \x
+	.2byte \y
 	.endm
 
+	@ TODO
 	@ Sets the warp destination that a warp to Warp 127 on Map 127.127 will connect to.
 	@ Useful when a map has warps that need to go to script-controlled locations (i.e. elevators).
-	.macro setdynamicwarp map:req, warp:req, X:req, Y:req
+	.macro setdynamicwarp map:req, warp:req, x:req, y:req
 	.byte 0x3f
 	map \map
 	.byte \warp
-	.2byte \X
-	.2byte \Y
+	.2byte \x
+	.2byte \y
 	.endm
 
 	@ Sets the destination that diving or emerging from a dive will take the player to.
-	.macro setdivewarp map:req, warp:req, X:req, Y:req
+	.macro setdivewarp map:req, warp:req, x:req, y:req
 	.byte 0x40
 	map \map
 	.byte \warp
-	.2byte \X
-	.2byte \Y
+	.2byte \x
+	.2byte \y
 	.endm
 
 	@ Sets the destination that falling into a hole will take the player to.
-	.macro setholewarp map:req, warp:req, X:req, Y:req
+	.macro setholewarp map:req, warp:req, x:req, y:req
 	.byte 0x41
 	map \map
 	.byte \warp
-	.2byte \X
-	.2byte \Y
+	.2byte \x
+	.2byte \y
 	.endm
 
-	@ Retrieves the player's zero-indexed X- and Y-coordinates in the map, and stores them in the specified variables.
-	.macro getplayerxy X:req, Y:req
+	@ Retrieves the player's zero-indexed x- and y-coordinates in the map, and stores them in the specified variables.
+	.macro getplayerxy x:req, y:req
 	.byte 0x42
-	.2byte \X
-	.2byte \Y
+	.2byte \x
+	.2byte \y
 	.endm
 
 	@ Retrieves the number of Pokemon in the player's party, and stores that number in VAR_RESULT.
@@ -482,7 +487,8 @@
 	.2byte \quantity
 	.endm
 
-	@ Removes quantity of item index from the player's Bag.
+	@ Removes quantity of item index from the player's Bag. If the player has fewer than 'quantity' in their bag
+	@ then none will be removed and VAR_RESULT will be set to FALSE. Otherwise it will be set to TRUE.
 	.macro removeitem index:req, quantity=1
 	.byte 0x45
 	.2byte \index
@@ -491,7 +497,7 @@
 
 	@ Checks if the player has enough space in their Bag to hold quantity more of item index. Sets VAR_RESULT to
 	@ TRUE if there is room, or FALSE is there is no room.
-	.macro checkitemspace index:req, quantity:req
+	.macro checkitemspace index:req, quantity=1
 	.byte 0x46
 	.2byte \index
 	.2byte \quantity
@@ -499,53 +505,53 @@
 
 	@ Checks if the player has quantity or more of item index in their Bag. Sets VAR_RESULT to TRUE if the player has
 	@ enough of the item, or FALSE if they have fewer than quantity of the item.
-	.macro checkitem index:req, quantity:req
+	.macro checkitem index:req, quantity=1
 	.byte 0x47
 	.2byte \index
 	.2byte \quantity
 	.endm
 
 	@ Checks which Bag pocket the specified item belongs in, and writes the pocket value (POCKET_*) to VAR_RESULT.
-	@ This script is used to show the name of the proper Bag pocket when the player receives an item via callstd (simplified to giveitem in XSE).
+	@ This is used to show the name of the proper Bag pocket when the player receives an item via callstd.
 	.macro checkitemtype index:req
 	.byte 0x48
 	.2byte \index
 	.endm
 
-	@ Adds a quantity amount of item index to the player's PC. Both arguments can be variables.
-	.macro addpcitem index:req, quantity:req
+	@ Adds a quantity amount of item index to the player's PC.
+	.macro addpcitem index:req, quantity=1
 	.byte 0x49
 	.2byte \index
 	.2byte \quantity
 	.endm
 
-	@ Checks for quantity amount of item index in the player's PC. Both arguments can be variables.
-	.macro checkpcitem index:req, quantity:req
+	@ Checks for quantity amount of item index in the player's PC.
+	.macro checkpcitem index:req, quantity=1
 	.byte 0x4a
 	.2byte \index
 	.2byte \quantity
 	.endm
 
-	@ Adds decoration to the player's PC. In FireRed, this command is a nop. (The argument is read, but not used for anything.)
+	@ Adds decoration to the player's PC.
 	.macro adddecoration decoration:req
 	.byte 0x4b
 	.2byte \decoration
 	.endm
 
-	@ Removes a decoration from the player's PC. In FireRed, this command is a nop. (The argument is read, but not used for anything.)
+	@ Removes a decoration from the player's PC.
 	.macro removedecoration decoration:req
 	.byte 0x4c
 	.2byte \decoration
 	.endm
 
-	@ Checks for decoration in the player's PC. In FireRed, this command is a nop. (The argument is read, but not used for anything.)
+	@ Checks for decoration in the player's PC.
 	.macro checkdecor decoration:req
 	.byte 0x4d
 	.2byte \decoration
 	.endm
 
-	@ Checks if the player has enough space in their PC to hold decoration. Sets VAR_RESULT to TRUE if there is room, or
-	@ FALSE is there is no room. In FireRed, this command is a nop. (The argument is read, but not used for anything.)
+	@ Checks if the player has enough space in their PC to hold decoration.
+	@ Sets VAR_RESULT to TRUE if there is room, or FALSE is there is no room.
 	.macro checkdecorspace decoration:req
 	.byte 0x4e
 	.2byte \decoration
@@ -568,7 +574,7 @@
 	.endm
 
 	@ Blocks script execution until the movements being applied to the specified (index) Object finish.
-	@ If the specified Object is 0x0000, then the command will block script execution until all Objects
+	@ If the specified Object is 0, then the command will block script execution until all Objects
 	@ affected by applymovement finish their movements. If the specified Object is not currently being
 	@ manipulated with applymovement, then this command does nothing.
 	@ If no map is specified, then the current map is used.
@@ -583,9 +589,8 @@
 		.endif
 	.endm
 
-	@ Attempts to hide the specified (index) Object on the specified (map_group, map_num) map,
-	@ by setting its visibility flag if it has a valid one. If the Object does not have a valid
-	@ visibility flag, this command does nothing.
+	@ Attempts to despawn the specified (index) Object on the specified (map_group, map_num) map.
+	@ It also sets the object's visibility flag if it has one.
 	@ If no map is specified, then the current map is used.
 	.macro removeobject index:req, map
 		.ifb \map
@@ -598,8 +603,8 @@
 		.endif
 	.endm
 
-	@ Unsets the specified (index) Object's visibility flag on the specified (map_group, map_num) map if it has a valid one.
-	@ If the Object does not have a valid visibility flag, this command does nothing.
+	@ Attempts to spawn the specified (index) Object the specified (map_group, map_num) map.
+	@ Note that unlike removeobject this does not modify the OObject's flag.
 	@ If no map is specified, then the current map is used.
 	.macro addobject index:req, map
 		.ifb \map
@@ -632,7 +637,7 @@
 	map \map
 	.endm
 
-	@ If the script was called by an Object, then that Object will turn to face toward the metatile that the player is standing on.
+	@ If the script was called by an Object, then that Object will turn to face toward the player.
 	.macro faceplayer
 	.byte 0x5a
 	.endm
@@ -643,7 +648,7 @@
 	.byte \direction
 	.endm
 
-	@ If the Trainer flag for Trainer index is not set, this command does absolutely nothing.
+	@ TODO
 	.macro trainerbattle type:req, trainer:req, local_id:req, pointer1:req, pointer2, pointer3, pointer4
 	.byte 0x5c
 	.byte \type
@@ -996,15 +1001,15 @@
 	.2byte \slot
 	.endm
 
-	@ Writes the name of the item at index item to the specified buffer. If the specified index is larger than
-	@ the number of items in the game (0x176), the name of item 0 ("????????") is buffered instead.
+	@ Writes the name of the item at index item to the specified buffer. If the specified index is >= ITEMS_COUNT,
+	@ then the name of ITEM_NONE ("????????") is buffered instead.
 	.macro bufferitemname out:req, item:req
 	.byte 0x80
 	.byte \out
 	.2byte \item
 	.endm
 
-	@ Writes the name of the decoration at index decoration to the specified buffer. In FireRed, this command is a nop.
+	@ Writes the name of the decoration at index 'decoration' to the specified buffer.
 	.macro bufferdecorationname out:req, decoration:req
 	.byte 0x81
 	.byte \out
@@ -1052,7 +1057,7 @@
 	.4byte \products
 	.endm
 
-	@ Apparent clone of pokemartdecoration.
+	@ Identical to pokemartdecoration, but with slight changes to the clerk dialogue. See uses of MART_TYPE_DECOR2.
 	.macro pokemartdecoration2 products:req
 	.byte 0x88
 	.4byte \products
@@ -1064,7 +1069,7 @@
 	.2byte \word
 	.endm
 
-	@ Sets a berry tree's specific berry and growth stage. In FireRed, this command is a nop.
+	@ Sets a berry tree's specific berry and growth stage.
 	.macro setberrytree tree_id:req, berry:req, growth_stage:req
 	.byte 0x8a
 	.byte \tree_id
@@ -1072,60 +1077,63 @@
 	.byte \growth_stage
 	.endm
 
-	@ This allows you to choose a Pokemon to use in a contest. In FireRed, this command sets the byte at 0x03000EA8 to 0x01.
+	@ This allows you to choose a Pokemon to use in a contest
 	.macro choosecontestmon
 	.byte 0x8b
 	.endm
 
-	@ Starts a contest. In FireRed, this command is a nop.
+	@ Starts a contest.
 	.macro startcontest
 	.byte 0x8c
 	.endm
 
-	@ Shows the results of a contest. In FireRed, this command is a nop.
+	@ Shows the results of a contest.
 	.macro showcontestresults
 	.byte 0x8d
 	.endm
 
-	@ Starts a contest over a link connection. In FireRed, this command is a nop.
+	@ Starts a contest over a link connection.
 	.macro contestlinktransfer
 	.byte 0x8e
 	.endm
 
-	@ Stores a random integer between 0 and limit in VAR_RESULT.
+	@ Stores a random integer between 0 and limit (exclusive of limit) in VAR_RESULT.
 	.macro random limit:req
 	.byte 0x8f
 	.2byte \limit
 	.endm
 
-	@ If check is 0x00, this command adds value to the player's money.
-	.macro addmoney value:req, check:req
+	@ Adds value to the player's money. If adding 'value' money would exceed MAX_MONEY, the player's money is set to MAX_MONEY.
+	@ If 'disable' is set to anything but 0 then this command does nothing.
+	.macro addmoney value:req, disable=0
 	.byte 0x90
 	.4byte \value
-	.byte \check
+	.byte \disable
 	.endm
 
-	@ If check is 0x00, this command subtracts value from the player's money.
-	.macro removemoney value:req, check:req
+	@ Subtracts value from the player's money. If the player has less than 'value' money, their money is set to 0.
+	@ If 'disable' is set to anything but 0 then this command does nothing.
+	.macro removemoney value:req, disable=0
 	.byte 0x91
 	.4byte \value
-	.byte \check
+	.byte \disable
 	.endm
 
-	@ If check is 0x00, this command will check if the player has money >= value; VAR_RESULT is set to TRUE if the player
-	@ has enough money, or FALSE if they do not.
-	.macro checkmoney value:req, check:req
+	@ Checks if the player has money >= value. VAR_RESULT is set to TRUE if the player has enough money, or FALSE if they do not.
+	@ If 'disable' is set to anything but 0 then this command does nothing.
+	.macro checkmoney value:req, disable=0
 	.byte 0x92
 	.4byte \value
-	.byte \check
+	.byte \disable
 	.endm
 
 	@ Spawns a secondary box showing how much money the player has.
-	.macro showmoneybox x:req, y:req, check:req
+	@ If 'disable' is set to anything but 0 then this command does nothing.
+	.macro showmoneybox x:req, y:req, disable=0
 	.byte 0x93
 	.byte \x
 	.byte \y
-	.byte \check
+	.byte \disable
 	.endm
 
 	@ Hides the secondary box spawned by showmoney. Consumption of the x and y arguments was dummied out.
@@ -1135,15 +1143,16 @@
 	.byte 0  @ \y
 	.endm
 
-	@ Updates the secondary box spawned by showmoney. Consumes but does not use arguments.
-	.macro updatemoneybox x:req, y:req
+	@ Updates the secondary box spawned by showmoney. Consumption of the x and y arguments was dummied out.
+	@ If 'disable' is set to anything but 0 then this command does nothing.
+	.macro updatemoneybox disable=0
 	.byte 0x95
-	.byte \x
-	.byte \y
-	.byte 0 @ 1 = don't perform this command. Always 0 in vanilla. Why this is a thing is beyond me.
+	.byte 0  @ \x
+	.byte 0  @ \y
+	.byte \disable
 	.endm
 
-	@ Gets the price reduction for the index given. In FireRed, this command is a nop.
+	@ Gets the price reduction for the index given.
 	.macro getpricereduction index:req
 	.byte 0x96
 	.2byte \index
@@ -1177,7 +1186,7 @@
 	.4byte \pointer
 	.endm
 
-	@ Executes the specified field move animation.
+	@ Executes the specified field effect animation.
 	.macro dofieldeffect animation:req
 	.byte 0x9c
 	.2byte \animation
@@ -1202,12 +1211,12 @@
 	.2byte \heallocation
 	.endm
 
-	@ Checks the player's gender. If male, then MALE (0) is stored in VAR_RESULT. If female, then FEMALE (1) is stored in VAR_RESULT.
+	@ Checks the player's gender. Stores the result (MALE (0) or FEMALE (1)) in VAR_RESULT.
 	.macro checkplayergender
 	.byte 0xa0
 	.endm
 
-	@ Plays the specified (species) Pokemon's cry. You can use waitcry to block script execution until the sound finishes.
+	@ Plays the specified (species) Pokemon's cry. You can use waitmoncry to block script execution until the sound finishes.
 	.macro playmoncry species:req, mode:req
 	.byte 0xa1
 	.2byte \species
@@ -1279,14 +1288,14 @@
 	.byte \direction
 	.endm
 
-	@ Opens the door metatile at (X, Y) with an animation.
+	@ Opens the door metatile at (x, y) with an animation.
 	.macro opendoor x:req, y:req
 	.byte 0xac
 	.2byte \x
 	.2byte \y
 	.endm
 
-	@ Closes the door metatile at (X, Y) with an animation.
+	@ Closes the door metatile at (x, y) with an animation.
 	.macro closedoor x:req, y:req
 	.byte 0xad
 	.2byte \x
@@ -1312,7 +1321,7 @@
 	.2byte \y
 	.endm
 
-	@ In Emerald, this command consumes its parameters and does nothing. In FireRed, this command is a nop.
+	@ Consumes its parameters and does nothing. It is implemented but unused in Ruby/Sapphire.
 	.macro addelevmenuitem a:req, b:req, c:req, d:req
 	.byte 0xb1
 	.byte \a
@@ -1321,27 +1330,33 @@
 	.2byte \d
 	.endm
 
-	@ In FireRed and Emerald, this command is a nop.
+	@ Does nothing. It is implemented but unused in Ruby/Sapphire.
 	.macro showelevmenu
 	.byte 0xb2
 	.endm
 
+	@ Gets the number of coins the player has and stores it in the variable 'out'.
 	.macro checkcoins out:req
 	.byte 0xb3
 	.2byte \out
 	.endm
 
+	@ Gives 'count' coins to the player, up to a total of MAX_COINS. 
+	@ If the player already has MAX_COINS then VAR_RESULT is set to TRUE, otherwise it is set to FALSE.
 	.macro addcoins count:req
 	.byte 0xb4
 	.2byte \count
 	.endm
 
+	@ Takes 'count' coins from the player.
+	@ If the player has fewer than 'count' coins then no coins are taken and VAR_RESULT is set to TRUE.
+	@ Otherwise VAR_RESULT is set to FALSE.
 	.macro removecoins count:req
 	.byte 0xb5
 	.2byte \count
 	.endm
 
-	@ Prepares to start a wild battle against a species at Level level holding item. Running this command will not affect
+	@ Prepares to start a wild battle against a 'species' at 'level' holding 'item'. Running this command will not affect
 	@ normal wild battles. You start the prepared battle with dowildbattle.
 	.macro setwildbattle species:req, level:req, item:req
 	.byte 0xb6
@@ -1419,14 +1434,16 @@
 	.byte \y
 	.endm
 
-	@ Increases the value of the specified game stat by 1. The stat's value will not be allowed to exceed 0x00FFFFFF.
+	@ Increases the value of the specified game stat by 1. The maximum value of a stat is 0xFFFFFF. See include/constants/game_stat.h
 	.macro incrementgamestat stat:req
 	.byte 0xc3
 	.byte \stat
 	.endm
 
 	@ Sets the destination that using an Escape Rope or Dig will take the player to.
-	.macro setescapewarp map:req, warp:req, x:req, y:req
+	@ The player will warp to the coordinates of the given 'warp'.
+	@ If 'warp' is set to an invalid id (e.g. 255) then the coordinates x/y will be used instead.
+	.macro setescapewarp map:req, warp:req, x=0, y=0
 	.byte 0xc4
 	map \map
 	.byte \warp
@@ -1446,42 +1463,33 @@
 	.2byte \box
 	.endm
 
-	@ Sets the color of the text in standard message boxes. 0x00 produces blue (male) text, 0x01 produces red (female) text,
-	@ 0xFF resets the color to the default for the current OW's gender, and all other values produce black text.
 	@ Used only in FireRed/LeafGreen, does nothing in Emerald.
 	.macro textcolor color:req
 	.byte 0xc7
 	.byte \color
 	.endm
 
-	@ The exact purpose of this command is unknown, but it is related to the blue help-text box that appears on the bottom
-	@ of the screen when the Main Menu is opened.
 	@ Used only in FireRed/LeafGreen, does nothing in Emerald.
 	.macro loadhelp pointer:req
 	.byte 0xc8
 	.4byte \pointer
 	.endm
 
-	@ The exact purpose of this command is unknown, but it is related to the blue help-text box that appears on the bottom of
-	@ the screen when the Main Menu is opened.
 	@ Used only in FireRed/LeafGreen, does nothing in Emerald.
 	.macro unloadhelp
 	.byte 0xc9
 	.endm
 
-	@ After using this command, all standard message boxes will use the signpost frame.
 	@ Used only in FireRed/LeafGreen, does nothing in Emerald.
 	.macro signmsg
 	.byte 0xca
 	.endm
 
-	@ Ends the effects of signmsg, returning message box frames to normal.
 	@ Used only in FireRed/LeafGreen, does nothing in Emerald.
 	.macro normalmsg
 	.byte 0xcb
 	.endm
 
-	@ Compares the value of a hidden variable to a dword.
 	@ Used only in FireRed/LeafGreen, does nothing in Emerald.
 	.macro comparehiddenvar a:req, value:req
 	.byte 0xcc
@@ -1489,26 +1497,25 @@
 	.4byte \value
 	.endm
 
-	@ Sets the Pokemon in the specified slot of the player party's eventLegal bit.
+	@ Sets the eventLegal bit for the Pokemon in the specified slot of the player's party.
 	.macro setmoneventlegal slot:req
 	.byte 0xcd
 	.2byte \slot
 	.endm
 
-	@ Checks if the Pokemon in the specified slot of the player's party has its eventLegal bit set. If it isn't set,
+	@ Checks if the eventLegal bit is set for the Pokemon in the specified slot of the player's party. If it isn't set,
 	@ VAR_RESULT is TRUE. If the bit is set (or if the specified slot is empty or invalid), VAR_RESULT is FALSE.
 	.macro checkmoneventlegal slot:req
 	.byte 0xce
 	.2byte \slot
 	.endm
 
-	@ Depending on factors I haven't managed to understand yet, this command may cause script execution to jump to the
-	@ offset specified by the pointer at 0x020375C0.
-	.macro gotoram
+	@ Jumps to the ram script saved from a Wonder Card. If there is no valid saved Wonder Card or if the
+	@ ram script is invalid then this does nothing.
+	.macro gotowondercardscript
 	.byte 0xcf
 	.endm
 
-	@ Sets worldmapflag to 1. This allows the player to Fly to the corresponding map, if that map has a flightspot.
 	@ Used only in FireRed/LeafGreen, does nothing in Emerald.
 	.macro setworldmapflag worldmapflag:req
 	.byte 0xd0
@@ -1516,7 +1523,9 @@
 	.endm
 
 	@ Clone of warpteleport? It is apparently only used in FR/LG, and only with specials.[source]
-	.macro warpteleport2 map:req, warp:req, x:req, y:req
+	@ The player will warp to the coordinates of the given 'warp'.
+	@ If 'warp' is set to an invalid id (e.g. 255) then the coordinates x/y will be used instead.
+	.macro warpteleport2 map:req, warp:req, x=0, y=0
 	.byte 0xd1
 	map \map
 	.byte \warp
@@ -1545,7 +1554,7 @@
 
 	@ For the rotating tile puzzles in Mossdeep Gym/Trick House Room 7. Allocates memory for the puzzle objects.
 	@ isTrickHouse is needed to determine which of the two maps the puzzle is on, in order to know where in the tileset
-	@ the puzzle tiles start. In FireRed, this command is a nop.
+	@ the puzzle tiles start.
 	.macro initrotatingtilepuzzle isTrickHouse:req
 	.byte 0xd5
 	.2byte \isTrickHouse
@@ -1556,10 +1565,12 @@
 	.byte 0xd6
 	.endm
 
-	.macro warpmossdeepgym map:req, warpId:req, x:req, y:req
+	@ The player will warp to the coordinates of the given 'warp'.
+	@ If 'warp' is set to an invalid id (e.g. 255) then the coordinates x/y will be used instead.
+	.macro warpmossdeepgym map:req, warp:req, x=0, y=0
 	.byte 0xd7
 	map \map
-	.byte \warpId
+	.byte \warp
 	.2byte \x
 	.2byte \y
 	.endm
@@ -1603,12 +1614,14 @@
 	.4byte \pointer
 	.endm
 
-	.macro warpsootopolislegend map:req, byte:req, word1:req, word2:req
+	@ The player will warp to the coordinates of the given 'warp'.
+	@ If 'warp' is set to an invalid id (e.g. 255) then the coordinates x/y will be used instead.
+	.macro warpsootopolislegend map:req, warp:req, x=0, y=0
 	.byte 0xe0
 	map \map
-	.byte \byte
-	.2byte \word1
-	.2byte \word2
+	.byte \warp
+	.2byte \x
+	.2byte \y
 	.endm
 
 	.macro buffercontesttypestring out:req, word:req
@@ -1617,10 +1630,9 @@
 	.2byte \word
 	.endm
 
-	@ Writes the name of the specified (item) item to the specified buffer. If the specified item is a Berry (0x85 - 0xAE) or
-	@ Poke Ball (0x4) and if the quantity is 2 or more, the buffered string will be pluralized ("IES" or "S" appended).
-	@ If the specified item is the Enigma Berry, I have no idea what this command does (but testing showed no pluralization).
-	@ If the specified index is larger than the number of items in the game (0x176), the name of item 0 ("????????") is buffered instead.
+	@ Writes the name of the specified (item) item to the specified buffer. If 'item' is a Berry or ITEM_POKE_BALL
+	@ and if the quantity is 2 or more, the buffered string will be pluralized ("IES" or "S" appended).
+	@ If the specified item is >= ITEMS_COUNT then the name of ITEM_NONE ("????????") is buffered instead.
 	.macro bufferitemnameplural out:req, item:req, quantity:req
 	.byte 0xe2
 	.byte \out
@@ -1753,6 +1765,7 @@
 	MSGBOX_YESNO = 5
 	MSGBOX_AUTOCLOSE = 6
 	MSGBOX_GETPOINTS = 9
+	MSGBOX_POKENAV = 10
 
 	YES = 1
 	NO  = 0
@@ -1762,6 +1775,10 @@
 	callstd \type
 	.endm
 
+	@ Gives 'amount' of the specified 'item' to the player and prints a message with fanfare.
+	@ If the player doesn't have space for all the items then as many are added as possible, the
+	@ message indicates there is no room, and VAR_RESULT is set to FALSE. 
+	@ Otherwise VAR_RESULT is set to TRUE, and the message indicates they have received the item(s).
 	.macro giveitem item:req, amount=1
 	setorcopyvar VAR_0x8000, \item
 	setorcopyvar VAR_0x8001, \amount