Add some macro comments

10 files changed, 462 insertions, 416 deletions

diff --git a/asm/macros/battle_frontier/apprentice.inc b/asm/macros/battle_frontier/apprentice.inc
index e9b098a18..5d9ab8e3b 100644
--- a/asm/macros/battle_frontier/apprentice.inc
+++ b/asm/macros/battle_frontier/apprentice.inc
@@ -1,22 +1,24 @@
-@ TODO: These need to have description comment
-
+	@ TRUE if the player has talked to the Apprentice and answered their level mode question
 	.macro apprentice_gavelvlmode
 	setvar VAR_0x8004, APPRENTICE_FUNC_GAVE_LVLMODE
 	special CallApprenticeFunction
 	.endm
 
+	@ Set the level mode the Apprentice should battle in
 	.macro apprentice_setlvlmode lvlmode:req
 	setvar VAR_0x8004, APPRENTICE_FUNC_SET_LVLMODE
 	setorcopyvar VAR_0x8005, \lvlmode
-	addvar VAR_0x8005, 1
+	addvar VAR_0x8005, 1  @ Apprentice lvl mode is +1 from regular lvl mode value
 	special CallApprenticeFunction
 	.endm
 
+	@ Question was answered, increment the number of questions answered
 	.macro apprentice_answeredquestion
 	setvar VAR_0x8004, APPRENTICE_FUNC_ANSWERED_QUESTION
 	special CallApprenticeFunction
 	.endm
 
+	@ Show the response selection box to answer the Apprentice question. Menus are defined as APPRENTICE_ASK_*
 	.macro apprentice_menu  which:req
 	setvar VAR_0x8004, APPRENTICE_FUNC_MENU
 	setvar VAR_0x8005, \which
@@ -24,16 +26,19 @@
 	waitstate
 	.endm
 
+	@ Shuffle and set the Apprentice party mons to pick between from their list of possible party species
 	.macro apprentice_shufflespecies
 	setvar VAR_0x8004, APPRENTICE_FUNC_SHUFFLE_SPECIES
 	special CallApprenticeFunction
 	.endm
 
+	@ Randomize the question data (e.g. moves to pick between) and shuffle the order to ask them in
 	.macro apprentice_randomizequestions
 	setvar VAR_0x8004, APPRENTICE_FUNC_RANDOMIZE_QUESTIONS
 	special CallApprenticeFunction
 	.endm
 
+	@ Print the APPRENTICE_MSG_* text for the current Apprentice
 	.macro apprentice_msg  waitbuttonpress:req, which:req
 	setvar VAR_0x8004, APPRENTICE_FUNC_PRINT_MSG
 	setvar VAR_0x8005, \waitbuttonpress
@@ -42,46 +47,54 @@
 	waitstate
 	.endm
 
+	@ Clear the data for the current Player Apprentice
 	.macro apprentice_reset
 	setvar VAR_0x8004, APPRENTICE_FUNC_RESET
 	special CallApprenticeFunction
 	.endm
 
+	@ Always returns TRUE. No side effect. May have been for debug or dummied for some other reason 
 	.macro apprentice_shouldcheckgone
 	setvar VAR_0x8004, APPRENTICE_FUNC_CHECK_GONE
 	special CallApprenticeFunction
 	.endm
 
+	@ Return the APPRENTICE_QUESTION_* value for the current question to ask
 	.macro apprentice_getquestion
 	setvar VAR_0x8004, APPRENTICE_FUNC_GET_QUESTION
 	special CallApprenticeFunction
 	.endm
 
+	@ Get the number of mons that have been chosen for the Apprentice's party so far
 	.macro apprentice_getnumpartymons
 	setvar VAR_0x8004, APPRENTICE_FUNC_GET_NUM_PARTY_MONS
 	special CallApprenticeFunction
 	.endm
 
+	@ Set the Apprentice party mon at the given slot. VAR_0x8005 is used implicitly as which of the 2 mons was selected
 	.macro apprentice_setpartymon  slot:req
 	copyvar VAR_0x8006, \slot
 	setvar VAR_0x8004, APPRENTICE_FUNC_SET_PARTY_MON
 	special CallApprenticeFunction
 	.endm
 
+	@ Allocate and set up data to track about the question
 	.macro apprentice_initquestion  which:req
 	setvar VAR_0x8004, APPRENTICE_FUNC_INIT_QUESTION_DATA
 	setvar VAR_0x8005, \which
 	special CallApprenticeFunction
 	.endm
 
+	@ Free allocated question data
 	.macro apprentice_freequestion
 	setvar VAR_0x8004, APPRENTICE_FUNC_FREE_QUESTION_DATA
 	special CallApprenticeFunction
 	.endm
 
-	.macro apprentice_buff  whichstringvar:req, tobuff:req
+	@ Buffer some APPRENTICE_BUFF_* string to the given stringvar (0 for STR_VAR_1, 1 for STR_VAR_2, 2 for STR_VAR_3)
+	.macro apprentice_buff  stringvar:req, tobuff:req
 	setvar VAR_0x8004, APPRENTICE_FUNC_BUFFER_STRING
-	setvar VAR_0x8005, \whichstringvar
+	setvar VAR_0x8005, \stringvar
 	.if \tobuff >= VARS_START
 	copyvar VAR_0x8006, \tobuff
 	.else
@@ -90,43 +103,51 @@
 	special CallApprenticeFunction
 	.endm
 
+	@ Set which move to use that the player chose (implicitly VAR_0x8005)
 	.macro apprentice_setmove
 	setvar VAR_0x8004, APPRENTICE_FUNC_SET_MOVE
 	special CallApprenticeFunction
 	.endm
 
+	@ Set which mon the Apprentice should lead with 
 	.macro apprentice_setleadmon  monId:req
 	copyvar VAR_0x8005, \monId
 	setvar VAR_0x8004, APPRENTICE_FUNC_SET_LEAD_MON
 	special CallApprenticeFunction
 	.endm
 
+	@ Open the Bag Menu for the player to choose an item to recommend as a held item
 	.macro apprentice_openbag
 	setvar VAR_0x8004, APPRENTICE_FUNC_OPEN_BAG
 	special CallApprenticeFunction
 	waitstate
 	.endm
 
+	@ Try and set the recommended held item. FALSE if the item has been recommended before, as Battle Frontier forbids using the same held item for multiple party mons
 	.macro apprentice_trysetitem
 	setvar VAR_0x8004, APPRENTICE_FUNC_TRY_SET_HELD_ITEM
 	special CallApprenticeFunction
 	.endm
 
+	@ Save the current Player Apprentice to the saveblock to make room for a new Apprentice
 	.macro apprentice_save
 	setvar VAR_0x8004, APPRENTICE_FUNC_SAVE
 	special CallApprenticeFunction
 	.endm
 
+	@ Set the object event gfx for the Apprentice based on their trainer class
 	.macro apprentice_setgfx
 	setvar VAR_0x8004, APPRENTICE_FUNC_SET_GFX
 	special CallApprenticeFunction
 	.endm
 
+	@ Always returns TRUE. No side effect. May have been for debug or dummied for some other reason 
 	.macro apprentice_shouldleave
 	setvar VAR_0x8004, APPRENTICE_FUNC_SHOULD_LEAVE
 	special CallApprenticeFunction
 	.endm
 
+	@ Shift the other saved Apprentices over to make room for saving a new Apprentice
 	.macro apprentice_shiftsaved
 	setvar VAR_0x8004, APPRENTICE_FUNC_SHIFT_SAVED
 	special CallApprenticeFunction
diff --git a/asm/macros/battle_frontier/battle_arena.inc b/asm/macros/battle_frontier/battle_arena.inc
index cd7e0aa1d..8280f5845 100644
--- a/asm/macros/battle_frontier/battle_arena.inc
+++ b/asm/macros/battle_frontier/battle_arena.inc
@@ -15,11 +15,11 @@
 	.macro arena_set data:req, val:req
 	setvar VAR_0x8004, BATTLE_ARENA_FUNC_SET_DATA
 	setvar VAR_0x8005, \data
-    .if \val >= VARS_START
-    copyvar VAR_0x8006, \val
-    .else
+	.if \val >= VARS_START
+	copyvar VAR_0x8006, \val
+	.else
 	setvar VAR_0x8006, \val
-    .endif
+	.endif
 	special CallBattleArenaFunction
 	.endm
 
diff --git a/asm/macros/battle_frontier/battle_dome.inc b/asm/macros/battle_frontier/battle_dome.inc
index 128470422..882c82e8b 100644
--- a/asm/macros/battle_frontier/battle_dome.inc
+++ b/asm/macros/battle_frontier/battle_dome.inc
@@ -133,6 +133,12 @@
 	special CallBattleDomeFunction
 	.endm
 
+	@ TODO: Document this macro and its function
+	.macro dome_21
+	setvar VAR_0x8004, BATTLE_DOME_FUNC_21
+	special CallBattleDomeFunction
+	.endm
+
 	@
 	.macro dome_inittrainers
 	setvar VAR_0x8004, BATTLE_DOME_FUNC_INIT_TRAINERS
diff --git a/asm/macros/battle_frontier/battle_factory.inc b/asm/macros/battle_frontier/battle_factory.inc
index f5ef7bda9..5a1eb33b7 100644
--- a/asm/macros/battle_frontier/battle_factory.inc
+++ b/asm/macros/battle_frontier/battle_factory.inc
@@ -1,103 +1,103 @@
-@ TODO: Add explanatory comments
-
-    @ 
-    .macro factory_init
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_INIT
-    special CallBattleFactoryFunction
-    .endm
-
-    @
-    .macro factory_get data:req
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GET_DATA
-    setvar VAR_0x8005, \data
-    special CallBattleFactoryFunction
-    .endm
-
-    @ 
-    .macro factory_set data:req, val=0xFFFF
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_DATA
-    setvar VAR_0x8005, \data
-    .if \val == 0xFFFF
-    @ argument not provided
-    .elseif \val >= VARS_START
-    copyvar VAR_0x8006, \val
-    .else
-    setvar VAR_0x8006, \val
-    .endif
-    special CallBattleFactoryFunction
-    .endm
-
-    @  
-    .macro factory_save challengeStatus:req
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SAVE
-    setvar VAR_0x8005, \challengeStatus
-    special CallBattleFactoryFunction
-    .endm
-
-    @  
-    .macro factory_rentmons
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SELECT_RENT_MONS
-    special CallBattleFactoryFunction
-    .endm
-
-    @ 
-    .macro factory_swapmons
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SWAP_RENT_MONS
-    special CallBattleFactoryFunction
-    .endm
-
-    @
-    .macro factory_setswapped
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_SWAPPED
-    special CallBattleFactoryFunction
-    .endm
-
-    @ 
-    .macro factory_setopponentmons
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_OPPONENT_MONS
-    special CallBattleFactoryFunction
-    .endm
-
-    @ 
-    .macro factory_setparties arg:req
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_PARTIES
-    setvar VAR_0x8005, \arg
-    special CallBattleFactoryFunction
-    .endm
-
-    @ 
-    .macro factory_setopponentgfx
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_OPPONENT_GFX
-    special CallBattleFactoryFunction
-    .endm
-
-    @  
-    .macro factory_generateopponentmons
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GENERATE_OPPONENT_MONS
-    special CallBattleFactoryFunction
-    .endm
-
-    @  
-    .macro factory_generaterentalmons
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GENERATE_RENTAL_MONS
-    special CallBattleFactoryFunction
-    .endm
-
-    @  
-    .macro factory_getopponentmontype
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GET_OPPONENT_MON_TYPE
-    special CallBattleFactoryFunction
-    .endm
-
-    @ 
-    .macro factory_getopponentstyle 
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GET_OPPONENT_STYLE
-    special CallBattleFactoryFunction
-    .endm
-
-    @  
-    .macro factory_resethelditems
-    setvar VAR_0x8004, BATTLE_FACTORY_FUNC_RESET_HELD_ITEMS
-    special CallBattleFactoryFunction
-    .endm
+@ TODO: Add explanatory comments to macros
+
+	@ Initialize the Battle Factory challenge
+	.macro factory_init
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_INIT
+	special CallBattleFactoryFunction
+	.endm
+
+	@ Get the value of some FACTORY_DATA_*. See GetBattleFactoryData for the data types that can be retrieved
+	.macro factory_get data:req
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GET_DATA
+	setvar VAR_0x8005, \data
+	special CallBattleFactoryFunction
+	.endm
+
+	@ Set some FACTORY_DATA_* to val. See SetBattleFactoryData for the data types that can be set
+	.macro factory_set data:req, val=0xFFFF
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_DATA
+	setvar VAR_0x8005, \data
+	.if \val == 0xFFFF
+	@ argument not provided
+	.elseif \val >= VARS_START
+	copyvar VAR_0x8006, \val
+	.else
+	setvar VAR_0x8006, \val
+	.endif
+	special CallBattleFactoryFunction
+	.endm
+
+	@ Save the game and set the challenge status
+	.macro factory_save challengeStatus:req
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SAVE
+	setvar VAR_0x8005, \challengeStatus
+	special CallBattleFactoryFunction
+	.endm
+
+	@  
+	.macro factory_rentmons
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SELECT_RENT_MONS
+	special CallBattleFactoryFunction
+	.endm
+
+	@ 
+	.macro factory_swapmons
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SWAP_RENT_MONS
+	special CallBattleFactoryFunction
+	.endm
+
+	@
+	.macro factory_setswapped
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_SWAPPED
+	special CallBattleFactoryFunction
+	.endm
+
+	@ 
+	.macro factory_setopponentmons
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_OPPONENT_MONS
+	special CallBattleFactoryFunction
+	.endm
+
+	@ 
+	.macro factory_setparties arg:req
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_PARTIES
+	setvar VAR_0x8005, \arg
+	special CallBattleFactoryFunction
+	.endm
+
+	@ 
+	.macro factory_setopponentgfx
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_OPPONENT_GFX
+	special CallBattleFactoryFunction
+	.endm
+
+	@  
+	.macro factory_generateopponentmons
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GENERATE_OPPONENT_MONS
+	special CallBattleFactoryFunction
+	.endm
+
+	@  
+	.macro factory_generaterentalmons
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GENERATE_RENTAL_MONS
+	special CallBattleFactoryFunction
+	.endm
+
+	@  
+	.macro factory_getopponentmontype
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GET_OPPONENT_MON_TYPE
+	special CallBattleFactoryFunction
+	.endm
+
+	@ 
+	.macro factory_getopponentstyle 
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GET_OPPONENT_STYLE
+	special CallBattleFactoryFunction
+	.endm
+
+	@  
+	.macro factory_resethelditems
+	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_RESET_HELD_ITEMS
+	special CallBattleFactoryFunction
+	.endm
 
diff --git a/asm/macros/battle_frontier/battle_palace.inc b/asm/macros/battle_frontier/battle_palace.inc
index c7fc6ded2..f326c1154 100644
--- a/asm/macros/battle_frontier/battle_palace.inc
+++ b/asm/macros/battle_frontier/battle_palace.inc
@@ -1,63 +1,63 @@
-    @ Initialize the Battle Palace challenge
-    .macro palace_init
-    setvar VAR_0x8004, BATTLE_PALACE_FUNC_INIT
-    special CallBattlePalaceFunction
-    .endm
-
-    @ Get the value of some PALACE_DATA_*. See GetPalaceData for the data types that can be retrieved
-    .macro palace_get data:req
-    setvar VAR_0x8004, BATTLE_PALACE_FUNC_GET_DATA
-    setvar VAR_0x8005, \data
-    special CallBattlePalaceFunction
-    .endm
-
-    @ Set some PALACE_DATA_* to val. See SetPalaceData for the data types that can be set
-    .macro palace_set data:req, val:req
-    setvar VAR_0x8004, BATTLE_PALACE_FUNC_SET_DATA
-    setvar VAR_0x8005, \data
-    setvar VAR_0x8006, \val
-    special CallBattlePalaceFunction
-    .endm
-
-    @ Get the id of the comment to be made while being led through the corridor
-    .macro palace_getcomment
-    setvar VAR_0x8004, BATTLE_PALACE_FUNC_GET_COMMENT_ID
-    special CallBattlePalaceFunction
-    .endm
-
-    @ Unused. Choose and set the opponent gfx id. The equivalent macro from Battle Tower is used instead
-    .macro palace_setopponent
-    setvar VAR_0x8004, BATTLE_PALACE_FUNC_SET_OPPONENT
-    special CallBattlePalaceFunction
-    .endm
-
-    @ Buffer the opponents intro speech to gStringVar4. Also used by Battle Arena and Factory 
-    .macro palace_getopponentintro
-    setvar VAR_0x8004, BATTLE_PALACE_FUNC_GET_OPPONENT_INTRO
-    special CallBattlePalaceFunction
-    .endm
-
-    @ Increments the current win streak by 1
-    .macro palace_incrementstreak
-    setvar VAR_0x8004, BATTLE_PALACE_FUNC_INCREMENT_STREAK
-    special CallBattlePalaceFunction
-    .endm
-
-    @ Save the game and set the challenge status
-    .macro palace_save challengeStatus:req
-    setvar VAR_0x8004, BATTLE_PALACE_FUNC_SAVE
-    setvar VAR_0x8005, \challengeStatus
-    special CallBattlePalaceFunction
-    .endm
-
-    @ Unused. Set the prize item to give from one of two lists of possible prizes, depending on streak.
-    .macro palace_setprize
-    setvar VAR_0x8004, BATTLE_PALACE_FUNC_SET_PRIZE
-    special CallBattleArenaFunction
-    .endm
-
-    @ Unused. Give the set prize item to the player. TRUE if room in Bag for prize, FALSE otherwise
-    .macro palace_giveprize
-    setvar VAR_0x8004, BATTLE_PALACE_FUNC_GIVE_PRIZE
-    special CallBattleArenaFunction
-    .endm
+	@ Initialize the Battle Palace challenge
+	.macro palace_init
+	setvar VAR_0x8004, BATTLE_PALACE_FUNC_INIT
+	special CallBattlePalaceFunction
+	.endm
+
+	@ Get the value of some PALACE_DATA_*. See GetPalaceData for the data types that can be retrieved
+	.macro palace_get data:req
+	setvar VAR_0x8004, BATTLE_PALACE_FUNC_GET_DATA
+	setvar VAR_0x8005, \data
+	special CallBattlePalaceFunction
+	.endm
+
+	@ Set some PALACE_DATA_* to val. See SetPalaceData for the data types that can be set
+	.macro palace_set data:req, val:req
+	setvar VAR_0x8004, BATTLE_PALACE_FUNC_SET_DATA
+	setvar VAR_0x8005, \data
+	setvar VAR_0x8006, \val
+	special CallBattlePalaceFunction
+	.endm
+
+	@ Get the id of the comment to be made while being led through the corridor
+	.macro palace_getcomment
+	setvar VAR_0x8004, BATTLE_PALACE_FUNC_GET_COMMENT_ID
+	special CallBattlePalaceFunction
+	.endm
+
+	@ Unused. Choose and set the opponent gfx id. The equivalent macro from Battle Tower is used instead
+	.macro palace_setopponent
+	setvar VAR_0x8004, BATTLE_PALACE_FUNC_SET_OPPONENT
+	special CallBattlePalaceFunction
+	.endm
+
+	@ Buffer the opponents intro speech to gStringVar4. Also used by Battle Arena and Factory 
+	.macro palace_getopponentintro
+	setvar VAR_0x8004, BATTLE_PALACE_FUNC_GET_OPPONENT_INTRO
+	special CallBattlePalaceFunction
+	.endm
+
+	@ Increments the current win streak by 1
+	.macro palace_incrementstreak
+	setvar VAR_0x8004, BATTLE_PALACE_FUNC_INCREMENT_STREAK
+	special CallBattlePalaceFunction
+	.endm
+
+	@ Save the game and set the challenge status
+	.macro palace_save challengeStatus:req
+	setvar VAR_0x8004, BATTLE_PALACE_FUNC_SAVE
+	setvar VAR_0x8005, \challengeStatus
+	special CallBattlePalaceFunction
+	.endm
+
+	@ Unused. Set the prize item to give from one of two lists of possible prizes, depending on streak.
+	.macro palace_setprize
+	setvar VAR_0x8004, BATTLE_PALACE_FUNC_SET_PRIZE
+	special CallBattleArenaFunction
+	.endm
+
+	@ Unused. Give the set prize item to the player. TRUE if room in Bag for prize, FALSE otherwise
+	.macro palace_giveprize
+	setvar VAR_0x8004, BATTLE_PALACE_FUNC_GIVE_PRIZE
+	special CallBattleArenaFunction
+	.endm
diff --git a/asm/macros/battle_frontier/battle_pike.inc b/asm/macros/battle_frontier/battle_pike.inc
index 150c7f02b..d40cb0bac 100644
--- a/asm/macros/battle_frontier/battle_pike.inc
+++ b/asm/macros/battle_frontier/battle_pike.inc
@@ -1,4 +1,4 @@
-@ TODO: Add explanatory comments
+@ TODO: Add explanatory comments to macros
 
 	@
 	.macro pike_setnextroom
@@ -6,14 +6,14 @@
 	special CallBattlePikeFunction
 	.endm
 
-	@
+	@ Get the value of some PIKE_DATA_*. See GetBattlePikeData for the data types that can be retrieved
 	.macro pike_get data:req
 	setvar VAR_0x8004, BATTLE_PIKE_FUNC_GET_DATA
 	setvar VAR_0x8005, \data
 	special CallBattlePikeFunction
 	.endm
 
-	@
+	@ Set some PIKE_DATA_* to val. See SetBattlePikeData for the data types that can be set
 	.macro pike_set data:req, val:req
 	setvar VAR_0x8004, BATTLE_PIKE_FUNC_SET_DATA
 	setvar VAR_0x8005, \data
@@ -166,7 +166,7 @@
 	special CallBattlePikeFunction
 	.endm
 
-	@ Initialize the Battle Arena challenge
+	@ Initialize the Battle Pike challenge
 	.macro pike_init
 	setvar VAR_0x8004, BATTLE_PIKE_FUNC_INIT
 	special CallBattlePikeFunction
diff --git a/asm/macros/battle_frontier/battle_pyramid.inc b/asm/macros/battle_frontier/battle_pyramid.inc
index a7b7afb89..0468e5956 100644
--- a/asm/macros/battle_frontier/battle_pyramid.inc
+++ b/asm/macros/battle_frontier/battle_pyramid.inc
@@ -1,97 +1,97 @@
-@ TODO: Add explanatory comments
+@ TODO: Add explanatory comments to macros
 
-    @ 
-    .macro pyramid_init
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_INIT
-    special CallBattlePyramidFunction 
-    .endm
+	@ Initialize the Battle Pyramid challenge
+	.macro pyramid_init
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_INIT
+	special CallBattlePyramidFunction 
+	.endm
 
-    @  
-    .macro pyramid_get data:req
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_GET_DATA
-    setvar VAR_0x8005, \data
-    special CallBattlePyramidFunction
-    .endm
+	@ Get the value of some PYRAMID_DATA_*. See GetBattlePyramidData for the data types that can be retrieved
+	.macro pyramid_get data:req
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_GET_DATA
+	setvar VAR_0x8005, \data
+	special CallBattlePyramidFunction
+	.endm
 
-    @   
-    .macro pyramid_set data:req, val:req
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_DATA
-    setvar VAR_0x8005, \data
-    setvar VAR_0x8006, \val
-    special CallBattlePyramidFunction
-    .endm
+	@ Set some PYRAMID_DATA_* to val. See SetBattlePyramidData for the data types that can be set
+	.macro pyramid_set data:req, val:req
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_DATA
+	setvar VAR_0x8005, \data
+	setvar VAR_0x8006, \val
+	special CallBattlePyramidFunction
+	.endm
 
-    @ 
-    .macro pyramid_save challengeStatus:req
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SAVE
-    setvar VAR_0x8005, \challengeStatus
-    special CallBattlePyramidFunction    
-    .endm
+	@ Save the game and set the challenge status
+	.macro pyramid_save challengeStatus:req
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SAVE
+	setvar VAR_0x8005, \challengeStatus
+	special CallBattlePyramidFunction
+	.endm
 
-    @  
-    .macro pyramid_setprize
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_PRIZE
-    special CallBattlePyramidFunction
-    .endm
+	@
+	.macro pyramid_setprize
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_PRIZE
+	special CallBattlePyramidFunction
+	.endm
 
-    @  
-    .macro pyramid_seedfloor
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SEED_FLOOR
-    special CallBattlePyramidFunction
-    .endm
+	@  
+	.macro pyramid_seedfloor
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SEED_FLOOR
+	special CallBattlePyramidFunction
+	.endm
 
-    @   
-    .macro pyramid_setitem
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_ITEM
-    special CallBattlePyramidFunction
-    .endm
+	@   
+	.macro pyramid_setitem
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_ITEM
+	special CallBattlePyramidFunction
+	.endm
 
-    @  
-    .macro pyramid_hideitem
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_HIDE_ITEM
-    special CallBattlePyramidFunction
-    .endm
+	@  
+	.macro pyramid_hideitem
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_HIDE_ITEM
+	special CallBattlePyramidFunction
+	.endm
 
-    @ 
-    .macro pyramid_inittrainers
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_INIT_TRAINERS
-    special CallBattlePyramidFunction 
-    .endm
+	@ 
+	.macro pyramid_inittrainers
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_INIT_TRAINERS
+	special CallBattlePyramidFunction 
+	.endm
 
-    @  
-    .macro pyramid_showhint
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SHOW_HINT_TEXT
-    special CallBattlePyramidFunction
-    .endm
+	@  
+	.macro pyramid_showhint
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SHOW_HINT_TEXT
+	special CallBattlePyramidFunction
+	.endm
 
-    @ VAR_RESULT is 1 if on a Pyramid floor, 2 if on the Pyramid peak   
-    .macro pyramid_inchallenge
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_IS_IN
-    special CallBattlePyramidFunction
-    .endm   
+	@ VAR_RESULT is 1 if player is on a Pyramid floor, 2 if on the Pyramid peak, 0 otherwise 
+	.macro pyramid_inchallenge
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_IS_IN
+	special CallBattlePyramidFunction
+	.endm   
 
-    @  
-    .macro pyramid_updatelight radius:req, mode:req
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_UPDATE_LIGHT
-    setvar VAR_0x8005, \radius
-    setvar VAR_0x8006, \mode
-    special CallBattlePyramidFunction
-    .endm  
+	@  
+	.macro pyramid_updatelight radius:req, mode:req
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_UPDATE_LIGHT
+	setvar VAR_0x8005, \radius
+	setvar VAR_0x8006, \mode
+	special CallBattlePyramidFunction
+	.endm  
 
-    @  
-    .macro pyramid_clearhelditems
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_CLEAR_HELD_ITEMS
-    special CallBattlePyramidFunction
-    .endm
+	@  
+	.macro pyramid_clearhelditems
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_CLEAR_HELD_ITEMS
+	special CallBattlePyramidFunction
+	.endm
 
-    @ BATTLE_PYRAMID_FUNC_SET_FLOOR_PALETTE 
-    .macro pyramid_setfloorpal
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_FLOOR_PALETTE
-    special CallBattlePyramidFunction
-    .endm             
+	@  
+	.macro pyramid_setfloorpal
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_FLOOR_PALETTE
+	special CallBattlePyramidFunction
+	.endm
 
-    @      
-    .macro pyramid_healparty
-    setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_RESTORE_PARTY
-    special CallBattlePyramidFunction 
-    .endm
+	@
+	.macro pyramid_healparty
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_RESTORE_PARTY
+	special CallBattlePyramidFunction 
+	.endm
diff --git a/asm/macros/battle_tent.inc b/asm/macros/battle_tent.inc
index c6f92ee15..663d1d344 100644
--- a/asm/macros/battle_tent.inc
+++ b/asm/macros/battle_tent.inc
@@ -1,163 +1,167 @@
-@ TODO: Add explanatory comments
-
 @ Verdanturf Tent
 
-    @   
-    .macro verdanturftent_init
-    setvar VAR_0x8004, VERDANTURF_TENT_FUNC_INIT
-    special CallVerdanturfTentFunction
-    .endm
-
-    @  
-    .macro verdanturftent_getprize
-    setvar VAR_0x8004, VERDANTURF_TENT_FUNC_GET_PRIZE
-    special CallVerdanturfTentFunction
-    .endm
-
-    @ Unused. 
-    .macro verdanturftent_setprize
-    setvar VAR_0x8004, VERDANTURF_TENT_FUNC_SET_PRIZE
-    special CallVerdanturfTentFunction
-    .endm
-
-    @ Unused. 
-    .macro verdanturftent_setopponentgfx
-    setvar VAR_0x8004, VERDANTURF_TENT_FUNC_SET_OPPONENT_GFX
-    special CallVerdanturfTentFunction
-    .endm
-
-    @ Buffers the opponents intro speech to STR_VAR_4. Despite being a Verdanturf Tent function, it serves the same purpose for all 3 tents. 
-    .macro battletent_getopponentintro
-    setvar VAR_0x8004, VERDANTURF_TENT_FUNC_GET_OPPONENT_INTRO
-    special CallVerdanturfTentFunction
-    .endm
-
-    @ 
-    .macro verdanturftent_save challengeStatus:req
-    setvar VAR_0x8004, VERDANTURF_TENT_FUNC_SAVE
-    setvar VAR_0x8005, \challengeStatus
-    special CallVerdanturfTentFunction  
-    .endm           
-
-    @   
-    .macro verdanturftent_setrandomprize
-    setvar VAR_0x8004, VERDANTURF_TENT_FUNC_SET_RANDOM_PRIZE
-    special CallVerdanturfTentFunction
-    .endm
-
-    @     
-    .macro verdanturftent_giveprize
-    setvar VAR_0x8004, VERDANTURF_TENT_FUNC_GIVE_PRIZE
-    special CallVerdanturfTentFunction
-    .endm  
+	@ Initialize the Verdanturf Battle Tent challenge
+	.macro verdanturftent_init
+	setvar VAR_0x8004, VERDANTURF_TENT_FUNC_INIT
+	special CallVerdanturfTentFunction
+	.endm
+
+	@ Get the current prize item id
+	.macro verdanturftent_getprize
+	setvar VAR_0x8004, VERDANTURF_TENT_FUNC_GET_PRIZE
+	special CallVerdanturfTentFunction
+	.endm
+
+	@ Unused. Set the prize item to be given
+	.macro verdanturftent_setprize unusedArg:req, itemId:req
+	setvar VAR_0x8004, VERDANTURF_TENT_FUNC_SET_PRIZE
+	setvar VAR_0x8005, \unusedArg
+	setvar VAR_0x8006, \itemId
+	special CallVerdanturfTentFunction
+	.endm
+
+	@ Unused. Set the opponent trainer and gfx. SetNextBattleTentOpponent is used through tower_setopponent instead
+	.macro verdanturftent_setopponentgfx
+	setvar VAR_0x8004, VERDANTURF_TENT_FUNC_SET_OPPONENT_GFX
+	special CallVerdanturfTentFunction
+	.endm
+
+	@ Buffers the opponents intro speech to STR_VAR_4. Despite being a Verdanturf Tent function, it serves the same purpose for all 3 tents. 
+	.macro battletent_getopponentintro
+	setvar VAR_0x8004, VERDANTURF_TENT_FUNC_GET_OPPONENT_INTRO
+	special CallVerdanturfTentFunction
+	.endm
+
+	@ Save the game and set the challenge status
+	.macro verdanturftent_save challengeStatus:req
+	setvar VAR_0x8004, VERDANTURF_TENT_FUNC_SAVE
+	setvar VAR_0x8005, \challengeStatus
+	special CallVerdanturfTentFunction  
+	.endm
+
+	@ Set the prize item as randomly selected from a list. Randomness unnecessary, as the list is only 1 item
+	.macro verdanturftent_setrandomprize
+	setvar VAR_0x8004, VERDANTURF_TENT_FUNC_SET_RANDOM_PRIZE
+	special CallVerdanturfTentFunction
+	.endm
+
+	@ Give the current prize item. FALSE if no room for prize
+	.macro verdanturftent_giveprize
+	setvar VAR_0x8004, VERDANTURF_TENT_FUNC_GIVE_PRIZE
+	special CallVerdanturfTentFunction
+	.endm  
 
 
 @ Fallarbor Tent
 
-    @  
-    .macro fallarbortent_init
-    setvar VAR_0x8004, FALLARBOR_TENT_FUNC_INIT
-    special CallFallarborTentFunction
-    .endm
-
-    @  
-    .macro fallarbortent_getprize
-    setvar VAR_0x8004, FALLARBOR_TENT_FUNC_GET_PRIZE
-    special CallFallarborTentFunction
-    .endm
-
-    @ Unused.
-    .macro fallarbortent_setprize
-    setvar VAR_0x8004, FALLARBOR_TENT_FUNC_SET_PRIZE
-    special CallFallarborTentFunction
-    .endm
-
-    @    
-    .macro fallarbortent_save challengeStatus:req
-    setvar VAR_0x8004, FALLARBOR_TENT_FUNC_SAVE
-    setvar VAR_0x8005, \challengeStatus
-    special CallFallarborTentFunction
-    .endm   
-
-    @   
-    .macro fallarbortent_setrandomprize
-    setvar VAR_0x8004, FALLARBOR_TENT_FUNC_SET_RANDOM_PRIZE
-    special CallFallarborTentFunction
-    .endm
-
-    @  
-    .macro fallarbortent_giveprize
-    setvar VAR_0x8004, FALLARBOR_TENT_FUNC_GIVE_PRIZE
-    special CallFallarborTentFunction
-    .endm    
-
-    @  
-    .macro fallarbortent_getopponentname
-    setvar VAR_0x8004, FALLARBOR_TENT_FUNC_GET_OPPONENT_NAME
-    special CallFallarborTentFunction
-    .endm 
+	@ Initialize the Fallarbor Battle Tent challenge
+	.macro fallarbortent_init
+	setvar VAR_0x8004, FALLARBOR_TENT_FUNC_INIT
+	special CallFallarborTentFunction
+	.endm
+
+	@ Get the current prize item id
+	.macro fallarbortent_getprize
+	setvar VAR_0x8004, FALLARBOR_TENT_FUNC_GET_PRIZE
+	special CallFallarborTentFunction
+	.endm
+
+	@ Unused. Set the prize item to be given
+	.macro fallarbortent_setprize unusedArg:req, itemId:req
+	setvar VAR_0x8004, FALLARBOR_TENT_FUNC_SET_PRIZE
+	setvar VAR_0x8005, \unusedArg
+	setvar VAR_0x8006, \itemId
+	special CallFallarborTentFunction
+	.endm
+
+	@ Save the game and set the challenge status
+	.macro fallarbortent_save challengeStatus:req
+	setvar VAR_0x8004, FALLARBOR_TENT_FUNC_SAVE
+	setvar VAR_0x8005, \challengeStatus
+	special CallFallarborTentFunction
+	.endm   
+
+	@ Set the prize item as randomly selected from a list. Randomness unnecessary, as the list is only 1 item
+	.macro fallarbortent_setrandomprize
+	setvar VAR_0x8004, FALLARBOR_TENT_FUNC_SET_RANDOM_PRIZE
+	special CallFallarborTentFunction
+	.endm
+
+	@ Give the current prize item. FALSE if no room for prize
+	.macro fallarbortent_giveprize
+	setvar VAR_0x8004, FALLARBOR_TENT_FUNC_GIVE_PRIZE
+	special CallFallarborTentFunction
+	.endm
+
+	@ Buffer the opponent trainers name to STR_VAR_1
+	.macro fallarbortent_getopponentname
+	setvar VAR_0x8004, FALLARBOR_TENT_FUNC_GET_OPPONENT_NAME
+	special CallFallarborTentFunction
+	.endm 
 
 
 @ Slateport Tent
 
-    @     
-    .macro slateporttent_init
-    setvar VAR_0x8004, SLATEPORT_TENT_FUNC_INIT
-    special CallSlateportTentFunction
-    .endm
-
-    @   
-    .macro slateporttent_getprize
-    setvar VAR_0x8004, SLATEPORT_TENT_FUNC_GET_PRIZE
-    special CallSlateportTentFunction
-    .endm
-
-    @ Unused.
-    .macro slateporttent_setprize
-    setvar VAR_0x8004, SLATEPORT_TENT_FUNC_SET_PRIZE
-    special CallSlateportTentFunction
-    .endm
-
-    @    
-    .macro slateporttent_save challengeStatus:req
-    setvar VAR_0x8004, SLATEPORT_TENT_FUNC_SAVE
-    setvar VAR_0x8005, \challengeStatus
-    special CallSlateportTentFunction
-    .endm   
-
-    @  
-    .macro slateporttent_setrandomprize
-    setvar VAR_0x8004, SLATEPORT_TENT_FUNC_SET_RANDOM_PRIZE
-    special CallSlateportTentFunction
-    .endm
-
-    @   
-    .macro slateporttent_giveprize
-    setvar VAR_0x8004, SLATEPORT_TENT_FUNC_GIVE_PRIZE
-    special CallSlateportTentFunction
-    .endm
-
-    @   
-    .macro slateporttent_rentmons
-    setvar VAR_0x8004, SLATEPORT_TENT_FUNC_SELECT_RENT_MONS
-    special CallSlateportTentFunction
-    .endm
-
-    @    
-    .macro slateporttent_swapmons
-    setvar VAR_0x8004, SLATEPORT_TENT_FUNC_SWAP_RENT_MONS
-    special CallSlateportTentFunction
-    .endm
-
-    @       
-    .macro slateporttent_generateopponentmons
-    setvar VAR_0x8004, SLATEPORT_TENT_FUNC_GENERATE_OPPONENT_MONS
-    special CallSlateportTentFunction
-    .endm 
-
-    @   
-    .macro slateporttent_generaterentalmons
-    setvar VAR_0x8004, SLATEPORT_TENT_FUNC_GENERATE_RENTAL_MONS
-    special CallSlateportTentFunction
-    .endm
+	@ Initialize the Slateport Battle Tent challenge
+	.macro slateporttent_init
+	setvar VAR_0x8004, SLATEPORT_TENT_FUNC_INIT
+	special CallSlateportTentFunction
+	.endm
+
+	@ Get the current prize item id
+	.macro slateporttent_getprize
+	setvar VAR_0x8004, SLATEPORT_TENT_FUNC_GET_PRIZE
+	special CallSlateportTentFunction
+	.endm
+
+	@ Unused. Set the prize item to be given
+	.macro slateporttent_setprize unusedArg:req, itemId:req
+	setvar VAR_0x8004, SLATEPORT_TENT_FUNC_SET_PRIZE
+	setvar VAR_0x8005, \unusedArg
+	setvar VAR_0x8006, \itemId
+	special CallSlateportTentFunction
+	.endm
+
+	@ Save the game and set the challenge status
+	.macro slateporttent_save challengeStatus:req
+	setvar VAR_0x8004, SLATEPORT_TENT_FUNC_SAVE
+	setvar VAR_0x8005, \challengeStatus
+	special CallSlateportTentFunction
+	.endm   
+
+	@ Set the prize item as randomly selected from a list. Randomness unnecessary, as the list is only 1 item 
+	.macro slateporttent_setrandomprize
+	setvar VAR_0x8004, SLATEPORT_TENT_FUNC_SET_RANDOM_PRIZE
+	special CallSlateportTentFunction
+	.endm
+
+	@ Give the current prize item. FALSE if no room for prize 
+	.macro slateporttent_giveprize
+	setvar VAR_0x8004, SLATEPORT_TENT_FUNC_GIVE_PRIZE
+	special CallSlateportTentFunction
+	.endm
+
+	@ Slateport Tent's version of factory_rentmons
+	.macro slateporttent_rentmons
+	setvar VAR_0x8004, SLATEPORT_TENT_FUNC_SELECT_RENT_MONS
+	special CallSlateportTentFunction
+	.endm
+
+	@ Slateport Tent's version of factory_swapmons
+	.macro slateporttent_swapmons
+	setvar VAR_0x8004, SLATEPORT_TENT_FUNC_SWAP_RENT_MONS
+	special CallSlateportTentFunction
+	.endm
+
+	@ Slateport Tent's version of factory_generateopponentmons
+	.macro slateporttent_generateopponentmons
+	setvar VAR_0x8004, SLATEPORT_TENT_FUNC_GENERATE_OPPONENT_MONS
+	special CallSlateportTentFunction
+	.endm 
+
+	@ Slateport Tent's version of factory_generaterentalmons
+	.macro slateporttent_generaterentalmons
+	setvar VAR_0x8004, SLATEPORT_TENT_FUNC_GENERATE_RENTAL_MONS
+	special CallSlateportTentFunction
+	.endm
 
diff --git a/asm/macros/trainer_hill.inc b/asm/macros/trainer_hill.inc
index 7ea1c77f6..d5c84fd02 100644
--- a/asm/macros/trainer_hill.inc
+++ b/asm/macros/trainer_hill.inc
@@ -1,90 +1,106 @@
-@ TODO: These need to have description comment
-
+	@ Initialize the Trainer Hill challenge and start the timer
 	.macro trainerhill_start
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_START
 	special CallTrainerHillFunction
 	.endm
 
+	@ 0 if not spoken to yet, 1 if spoken to but not received prize, 2 if received prize
 	.macro trainerhill_getownerstate
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_GET_OWNER_STATE
 	special CallTrainerHillFunction
 	.endm
 
+	@ Try to give prize. 0 if given successfully, 1 if no room for prize, 2 if giving prize should be skipped
 	.macro trainerhill_giveprize
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_GIVE_PRIZE
 	special CallTrainerHillFunction
 	.endm
 
+	@ Check the final challenge time. 0 if new record, 1 if not, 2 if time has already been checked
 	.macro trainerhill_finaltime
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_CHECK_FINAL_TIME
 	special CallTrainerHillFunction
 	.endm
 
+	@ Resume the timer. Wont resume if owner has been spoken to or max time has been reached
 	.macro trainerhill_resumetimer
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_RESUME_TIMER
 	special CallTrainerHillFunction
 	.endm
 
+	@ Set player lost the challenge (trainerHill.hasLost) to TRUE
 	.macro trainerhill_lost
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_SET_LOST
 	special CallTrainerHillFunction
 	.endm
 
+	@ Get the current challenge status (TRAINER_HILL_PLAYER_STATUS_*)
 	.macro trainerhill_getstatus
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_GET_CHALLENGE_STATUS
 	special CallTrainerHillFunction
 	.endm
 
+	@ Buffer the current timer to string vars (mins to STR_VAR_1, secs to STR_VAR_2, fraction of sec to STR_VAR_3)
 	.macro trainerhill_gettime
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_GET_CHALLENGE_TIME
 	special CallTrainerHillFunction
 	.endm
 
+	@ FALSE if fewer than all 4 floors used, TRUE otherwise. Only FALSE in JP-exclusive modes
 	.macro trainerhill_allfloorsused
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_GET_ALL_FLOORS_USED
 	special CallTrainerHillFunction
 	.endm
 
+	@ Unknown, dummied. Only side effect is setting VAR_RESULT to 0.
 	.macro trainerhill_clearresult
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_CLEAR_RESULT
 	special CallTrainerHillFunction
 	.endm
 
+	@ TRUE if currently in a Trainer Hill challenge
 	.macro trainerhill_inchallenge
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_IN_CHALLENGE
 	special CallTrainerHillFunction
 	.endm
 
+	@ Show the post battle text for the spoken to Trainer Hill trainer
 	.macro trainerhill_postbattletext
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_POST_BATTLE_TEXT
 	special CallTrainerHillFunction
 	.endm
 
+	@ Set all Trainer Hill trainers defeated
 	.macro trainerhill_settrainerflags
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_SET_ALL_TRAINER_FLAGS
 	special CallTrainerHillFunction
 	.endm
 
+	@ TRUE if the game has been saved for the challenge, FALSE otherwise
 	.macro trainerhill_getsaved
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_GET_GAME_SAVED
 	special CallTrainerHillFunction
 	.endm
 
+	@ Set that the game has been saved for the challenge
 	.macro trainerhill_setsaved
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_SET_GAME_SAVED
 	special CallTrainerHillFunction
 	.endm
 
+	@ Clear that the game has been saved for the challenge
 	.macro trainerhill_clearsaved
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_CLEAR_GAME_SAVED
 	special CallTrainerHillFunction
 	.endm
 
+	@ FALSE if the Trainer Hill challenge was lost, TRUE otherwise
 	.macro trainerhill_getwon
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_GET_WON
 	special CallTrainerHillFunction
 	.endm
 
+	@ Set the challenge mode to HILL_TAG_* (Normal, Variety, Unique, or Expert)
 	.macro trainerhill_settag tag:req
 	setvar VAR_0x8004, TRAINER_HILL_FUNC_SET_TAG
 	copyvar VAR_0x8005, \tag
diff --git a/data/maps/BattleFrontier_BattleDomeLobby/scripts.inc b/data/maps/BattleFrontier_BattleDomeLobby/scripts.inc
index 67fccf7d6..8d594695c 100644
--- a/data/maps/BattleFrontier_BattleDomeLobby/scripts.inc
+++ b/data/maps/BattleFrontier_BattleDomeLobby/scripts.inc
@@ -5,8 +5,7 @@ BattleFrontier_BattleDomeLobby_MapScripts:: @ 82497E2
 	.byte 0
 
 BattleFrontier_BattleDomeLobby_MapScript1_2497F2: @ 82497F2
-	setvar VAR_0x8004, BATTLE_DOME_FUNC_21
-	special CallBattleDomeFunction
+	dome_21
 	end
 
 BattleFrontier_BattleDomeLobby_MapScript2_2497FB: @ 82497FB