Resolve some "???" comments

15 files changed, 32 insertions, 24 deletions

diff --git a/constants/misc_constants.asm b/constants/misc_constants.asm
index 3847cf89..db60113a 100644
--- a/constants/misc_constants.asm
+++ b/constants/misc_constants.asm
@@ -13,6 +13,7 @@ FEMALE EQU 1
 	const CHECK_FLAG
 
 ; G/S version ID: 0 = Gold, 1 = Silver (used by checkver)
+; Mystery Gift uses incremented values 1 and 2
 IF DEF(_GOLD)
 GS_VERSION EQU 0
 ELIF DEF(_SILVER)
@@ -20,6 +21,7 @@ GS_VERSION EQU 1
 ENDC
 ; Pokémon Pikachu 2, a step counter / virtual pet device (used by Mystery Gift)
 POKEMON_PIKACHU_2_VERSION EQU 3
+RESERVED_GAME_VERSION EQU 4
 
 ; save file corruption check values
 SAVE_CHECK_VALUE_1 EQU 99
diff --git a/data/player_names.asm b/data/player_names.asm
index 3291ea66..165fa8cf 100644
--- a/data/player_names.asm
+++ b/data/player_names.asm
@@ -21,5 +21,5 @@ ELIF DEF(_SILVER)
 	db "OSCAR@"
 	db "MAX@"
 ENDC
-	db 2 ; ????
+	db 2 ; title indent
 	db "NAME@" ; title
diff --git a/data/predef_pointers.asm b/data/predef_pointers.asm
index f36f8307..45a56545 100644
--- a/data/predef_pointers.asm
+++ b/data/predef_pointers.asm
@@ -76,4 +76,4 @@ PredefPointers::
 	add_predef NewPokedexEntry
 	add_predef UnusedFrontpicPredef
 	add_predef UpdateTimePredef
-	dbw -1, InexplicablyEmptyFunction ; ???
+	dbw -1, DummyEndPredef ; pointless
diff --git a/engine/battle/core.asm b/engine/battle/core.asm
index 02f80eef..3826a182 100644
--- a/engine/battle/core.asm
+++ b/engine/battle/core.asm
@@ -2304,17 +2304,19 @@ WinTrainerBattle:
 	call BattleWinSlideInEnemyTrainerFrontpic
 	ld c, 40
 	call DelayFrames
+
 	ld a, [wBattleType]
 	cp BATTLETYPE_CANLOSE
 	jr nz, .skip_heal
 	predef HealParty
 .skip_heal
+
 	ld a, [wDebugFlags]
 	bit DEBUG_BATTLE_F, a
-	jr nz, .GiveMoney
+	jr nz, .skip_win_loss_text
 	call PrintWinLossText
+.skip_win_loss_text
 
-.GiveMoney:
 	ld a, [wAmuletCoin]
 	and a
 	call nz, .DoubleReward
@@ -2576,7 +2578,8 @@ UpdateFaintedPlayerMon:
 	ld a, [wWhichMonFaintedFirst]
 	and a
 	ret z
-	ret ; ??????????
+	; code was probably dummied out here
+	ret
 
 AskUseNextPokemon:
 	call EmptyBattleTextbox
@@ -2971,7 +2974,8 @@ EnemySwitch_SetMode:
 	jp ShowSetEnemyMonAndSendOutAnimation
 
 CheckWhetherSwitchmonIsPredetermined:
-; returns carry if: ???
+; returns the enemy switchmon index in b, or
+; returns carry if the index is not yet determined.
 	ld a, [wLinkMode]
 	and a
 	jr z, .not_linked
@@ -2993,7 +2997,7 @@ CheckWhetherSwitchmonIsPredetermined:
 .check_wBattleHasJustStarted
 	ld a, [wBattleHasJustStarted]
 	and a
-	ld b, $0
+	ld b, 0
 	jr nz, .return_carry
 
 	and a
diff --git a/engine/battle/move_effects/spite.asm b/engine/battle/move_effects/spite.asm
index 06627268..3e1c2f9b 100644
--- a/engine/battle/move_effects/spite.asm
+++ b/engine/battle/move_effects/spite.asm
@@ -4,7 +4,7 @@ BattleCommand_Spite:
 	ld a, [wAttackMissed]
 	and a
 	jp nz, .failed
-	ld bc, PARTYMON_STRUCT_LENGTH ; ????
+	ld bc, PARTYMON_STRUCT_LENGTH ; unused
 	ld hl, wEnemyMonMoves
 	ldh a, [hBattleTurn]
 	and a
diff --git a/engine/battle_anims/functions.asm b/engine/battle_anims/functions.asm
index a38bf152..a26c106c 100644
--- a/engine/battle_anims/functions.asm
+++ b/engine/battle_anims/functions.asm
@@ -124,17 +124,17 @@ BattleAnimFunction_ThrowFromUserToTarget:
 	ld hl, BATTLEANIMSTRUCT_YCOORD
 	add hl, bc
 	dec [hl]
-	; Decrease ??? and hold onto its previous value (argument of the sine function)
+	; Decrease var1 and hold onto its previous value (argument of the sine function)
 	ld hl, BATTLEANIMSTRUCT_VAR1
 	add hl, bc
 	ld a, [hl]
 	dec [hl]
-	; Get ???, which is the amplitude of the sine function
+	; Get param (amplitude of the sine function)
 	ld hl, BATTLEANIMSTRUCT_PARAM
 	add hl, bc
 	ld d, [hl]
 	call BattleAnim_Sine
-	; Store the result in the Y offset
+	; Store the sine result in the Y offset
 	ld hl, BATTLEANIMSTRUCT_YOFFSET
 	add hl, bc
 	ld [hl], a
diff --git a/engine/events/poisonstep_pals.asm b/engine/events/poisonstep_pals.asm
index 9ef8b99e..aaea0cc9 100644
--- a/engine/events/poisonstep_pals.asm
+++ b/engine/events/poisonstep_pals.asm
@@ -3,7 +3,8 @@ LoadPoisonBGPals:
 	ldh a, [hCGB]
 	and a
 	ret nz
-	ret ; ????
+	; code was probably dummied out here
+	ret
 
 .LoadPals:
 	ldh a, [hCGB]
diff --git a/engine/link/mystery_gift.asm b/engine/link/mystery_gift.asm
index f6ddc93a..e3fef8dd 100644
--- a/engine/link/mystery_gift.asm
+++ b/engine/link/mystery_gift.asm
@@ -86,7 +86,7 @@ DoMysteryGift:
 	jr z, .skip_append_save
 	call .AddMysteryGiftPartnerID
 	ld a, [wMysteryGiftGameVersion]
-	cp 4 ; ???
+	cp RESERVED_GAME_VERSION
 	jr z, .skip_append_save
 	call .SaveMysteryGiftTrainerName
 .skip_append_save
diff --git a/engine/overworld/events.asm b/engine/overworld/events.asm
index ee2facbe..7e1d8a4c 100644
--- a/engine/overworld/events.asm
+++ b/engine/overworld/events.asm
@@ -888,7 +888,7 @@ CountStep:
 	; Increase the EXP of (both) DayCare Pokemon by 1.
 	farcall DayCareStep
 
-	; Every four steps, deal damage to all Poisoned Pokemon
+	; Every 4 steps, deal damage to all poisoned Pokemon.
 	ld hl, wPoisonStepCount
 	ld a, [hl]
 	cp 4
diff --git a/engine/overworld/map_objects.asm b/engine/overworld/map_objects.asm
index 3d3b1cab..3c58f60f 100644
--- a/engine/overworld/map_objects.asm
+++ b/engine/overworld/map_objects.asm
@@ -1755,7 +1755,8 @@ StepFunction_ScreenShake:
 	ret
 
 StepFunction_16:
-	call Field1c_AnonJumptable ; ????
+	call Field1c_AnonJumptable
+	; jumptable was dummied out here
 
 StepFunction_17:
 	call Field1c_AnonJumptable
diff --git a/engine/pokedex/pokedex.asm b/engine/pokedex/pokedex.asm
index befc2f4c..873a6e3c 100644
--- a/engine/pokedex/pokedex.asm
+++ b/engine/pokedex/pokedex.asm
@@ -513,7 +513,8 @@ Pokedex_InitOptionScreen:
 	call ClearSprites
 	call Pokedex_DrawOptionScreenBG
 	call Pokedex_InitArrowCursor
-	ld a, [wCurDexMode] ; Index of the topmost visible item in a scrolling menu ???
+	; point cursor to the current dex mode (modes == menu item indexes)
+	ld a, [wCurDexMode]
 	ld [wDexArrowCursorPosIndex], a
 	call Pokedex_DisplayModeDescription
 	call WaitBGMap
@@ -1171,7 +1172,7 @@ Pokedex_DrawDexEntryScreenBG:
 .Height:
 	db "HT  ?", $5e, "??", $5f, -1 ; HT  ?'??"
 .Weight:
-	db "WT   ???lb", -1 ; WT   ???lb
+	db "WT   ???lb", -1
 .MenuItems:
 	db $3b, " PAGE AREA CRY PRNT", -1
 
diff --git a/engine/printer/printer_serial.asm b/engine/printer/printer_serial.asm
index f717ad38..f3c0709b 100644
--- a/engine/printer/printer_serial.asm
+++ b/engine/printer/printer_serial.asm
@@ -85,7 +85,7 @@ Print_InitPrinterHandshake:
 
 Printer_StartTransmittingTilemap:
 	call Printer_ResetData
-	; check ???
+	; check remaining tile data
 	ld hl, wPrinterRowIndex
 	ld a, [hl]
 	and a
diff --git a/home/map.asm b/home/map.asm
index 75281a1b..4146eaf0 100644
--- a/home/map.asm
+++ b/home/map.asm
@@ -2142,10 +2142,8 @@ LoadMapTileset::
 	pop hl
 	ret
 
-InexplicablyEmptyFunction::
-; unused
-; Inexplicably empty.
-; Seen in PredefPointers.
+DummyEndPredef::
+; Unused function at the end of PredefPointers.
 rept 16
 	nop
 endr
diff --git a/home/menu.asm b/home/menu.asm
index 8fb7c418..91866692 100644
--- a/home/menu.asm
+++ b/home/menu.asm
@@ -194,7 +194,7 @@ PlaceVerticalMenuItems::
 	ld a, [de]
 	ld c, a
 	inc de
-	ld b, $0
+	ld b, 0
 	add hl, bc
 	jp PlaceString
 
diff --git a/home/trainers.asm b/home/trainers.asm
index a5be4068..eb1121bc 100644
--- a/home/trainers.asm
+++ b/home/trainers.asm
@@ -230,7 +230,8 @@ CheckTrainerFlag:: ; unreferenced
 PrintWinLossText::
 	ld a, [wBattleType]
 	cp BATTLETYPE_CANLOSE
-	jr .canlose ; ??????????
+	; code was probably dummied out here
+	jr .canlose
 
 ; unused
 	ld hl, wWinTextPointer