Resolve some "???" comments

constants/misc_constants.asm

@@ -13,9 +13,11 @@ 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
 GS_VERSION EQU 0
 ; 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

data/player_names.asm

@@ -33,5 +33,5 @@ FemalePlayerNameArray:
 	db "AMANDA@"
 	db "JUANA@"
 	db "JODI@"
-	db 2 ; displacement
+	db 2 ; title indent
 	db " NAME @" ; title

data/predef_pointers.asm

@@ -81,4 +81,4 @@ PredefPointers::
 	add_predef AnimateFrontpic
 	add_predef Unused_HOF_AnimateAlignedFrontpic
 	add_predef HOF_AnimateFrontpic
-	dbw -1, InexplicablyEmptyFunction ; ???
+	dbw -1, DummyEndPredef ; pointless

engine/battle/core.asm

@@ -2366,18 +2366,20 @@ 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, .skip_win_loss_text
 	call PrintWinLossText
-
 .skip_win_loss_text
-	jp .GiveMoney
+
+	jp .give_money
 
 .mobile
 	call BattleWinSlideInEnemyTrainerFrontpic
@@ -2405,7 +2407,7 @@ WinTrainerBattle:
 	call ClearBGPalettes
 	ret
 
-.GiveMoney:
+.give_money
 	ld a, [wAmuletCoin]
 	and a
 	call nz, .DoubleReward
@@ -2678,7 +2680,8 @@ UpdateFaintedPlayerMon:
 	ld a, [wWhichMonFaintedFirst]
 	and a
 	ret z
-	ret ; ??????????
+	; code was probably dummied out here
+	ret
 
 AskUseNextPokemon:
 	call EmptyBattleTextbox
@@ -3160,7 +3163,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
@@ -3182,7 +3186,7 @@ CheckWhetherSwitchmonIsPredetermined:
 .check_wBattleHasJustStarted
 	ld a, [wBattleHasJustStarted]
 	and a
-	ld b, $0
+	ld b, 0
 	jr nz, .return_carry
 
 	and a

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

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

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]

engine/link/mystery_gift.asm

@@ -88,7 +88,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
 	farcall RestoreMobileEventIndex

engine/overworld/events.asm

@@ -900,7 +900,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

engine/overworld/map_objects.asm

@@ -1756,7 +1756,8 @@ StepFunction_ScreenShake:
 	ret
 
 StepFunction_16:
-	call Field1c_AnonJumptable ; ????
+	call Field1c_AnonJumptable
+	; jumptable was dummied out here
 
 StepFunction_17:
 	call Field1c_AnonJumptable

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
 

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

home/map.asm

@@ -2299,10 +2299,8 @@ LoadMapTileset::
 	pop hl
 	ret
 
-InexplicablyEmptyFunction::
-; unused
-; Inexplicably empty.
-; Seen in PredefPointers.
+DummyEndPredef::
+; Unused function at the end of PredefPointers.
 rept 16
 	nop
 endr

home/menu.asm

@@ -200,7 +200,7 @@ PlaceVerticalMenuItems::
 	ld a, [de]
 	ld c, a
 	inc de
-	ld b, $0
+	ld b, 0
 	add hl, bc
 	jp PlaceString
 

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