Thoroughly document debug code (#410)

engine/debug/debug_menu.asm

@@ -56,7 +56,7 @@ IF DEF(_DEBUG)
 
 	; DEBUG
 	ld hl, wd732
-	set 1, [hl]
+	set BIT_DEBUG_MODE, [hl]
 	jp StartNewGameDebug
 
 DebugBattlePlayerName:
@@ -72,18 +72,23 @@ ELSE
 	ret
 ENDC
 
-TestBattle:
+TestBattle: ; unreferenced except in _DEBUG
 .loop
 	call GBPalNormal
 
-	; Don't mess around
-	; with obedience.
+	; Don't mess around with obedience.
 	ld a, 1 << BIT_EARTHBADGE
 	ld [wObtainedBadges], a
 
 	ld hl, wFlags_D733
 	set BIT_TEST_BATTLE, [hl]
 
+	; wNumBagItems and wBagItems are not initialized here,
+	; and their garbage values happen to act as if EXP_ALL
+	; is in the bag at the end of the test battle.
+	; pokeyellow fixes this by initializing them with a
+	; list of items.
+
 	; Reset the party.
 	ld hl, wPartyCount
 	xor a
@@ -91,8 +96,7 @@ TestBattle:
 	dec a
 	ld [hl], a
 
-	; Give the player a
-	; level 20 Rhydon.
+	; Give the player a level 20 Rhydon.
 	ld a, RHYDON
 	ld [wcf91], a
 	ld a, 20
@@ -102,15 +106,14 @@ TestBattle:
 	ld [wCurMap], a
 	call AddPartyMon
 
-	; Fight against a
-	; level 20 Rhydon.
+	; Fight against a level 20 Rhydon.
 	ld a, RHYDON
 	ld [wCurOpponent], a
 
 	predef InitOpponent
 
-	; When the battle ends,
-	; do it all again.
+	; When the battle ends, do it all again.
+	; There are some graphical quirks in SGB mode.
 	ld a, 1
 	ld [wUpdateSpritesEnabled], a
 	ldh [hAutoBGTransferEnabled], a

engine/debug/debug_party.asm

@@ -1,13 +1,5 @@
-; This function is a debugging feature to give the player Tsunekazu Ishihara's
-; favorite Pokemon. This is indicated by the overpowered Exeggutor, which
-; Ishihara (president of Creatures Inc.) said was his favorite Pokemon in an ABC
-; interview on February 8, 2000.
-; "Exeggutor is my favorite. That's because I was always using this character
-; while I was debugging the program."
-; http://www.ign.com/articles/2000/02/09/abc-news-pokamon-chat-transcript
-
-SetIshiharaTeam:
-	ld de, IshiharaTeam
+SetDebugNewGameParty: ; unreferenced except in _DEBUG
+	ld de, DebugNewGameParty
 .loop
 	ld a, [de]
 	cp -1
@@ -20,7 +12,11 @@ SetIshiharaTeam:
 	call AddPartyMon
 	jr .loop
 
-IshiharaTeam:
+DebugNewGameParty: ; unreferenced except in _DEBUG
+	; Exeggutor is the only debug party member shared with Red, Green, and Japanese Blue.
+	; "Tsunekazu Ishihara: Exeggutor is my favorite. That's because I was
+	; always using this character while I was debugging the program."
+	; From https://web.archive.org/web/20000607152840/http://pocket.ign.com/news/14973.html
 	db EXEGGUTOR, 90
 IF DEF(_DEBUG)
 	db MEW, 5
@@ -35,13 +31,13 @@ IF DEF(_DEBUG)
 ENDC
 	db -1 ; end
 
-DebugStart:
+PrepareNewGameDebug: ; dummy except in _DEBUG
 IF DEF(_DEBUG)
 	xor a ; PLAYER_PARTY_DATA
 	ld [wMonDataLocation], a
 
 	; Fly anywhere.
-	dec a ; $ff
+	dec a ; $ff (all bits)
 	ld [wTownVisitedFlag], a
 	ld [wTownVisitedFlag + 1], a
 
@@ -49,7 +45,7 @@ IF DEF(_DEBUG)
 	ld a, ~(1 << BIT_EARTHBADGE)
 	ld [wObtainedBadges], a
 
-	call SetIshiharaTeam
+	call SetDebugNewGameParty
 
 	; Exeggutor gets four HM moves.
 	ld hl, wPartyMon1Moves