Label and document a bunch of bank 0 and 1 functions

7 files changed, 156 insertions, 111 deletions

diff --git a/src/engine/bank01.asm b/src/engine/bank01.asm
index 85bf0c8..31df46c 100644
--- a/src/engine/bank01.asm
+++ b/src/engine/bank01.asm
@@ -64,7 +64,7 @@ TryContinueDuel: ; 406f (1:406f)
 	jr c, FailedToContinueDuel
 ;	fallthrough
 
-ContinueDuel: ; 407a (1:407a)
+_ContinueDuel: ; 407a (1:407a)
 	ld hl, sp+$00
 	ld a, l
 	ld [wDuelReturnAddress], a
@@ -1600,7 +1600,7 @@ Func_4ad6: ; 4ad6 (1:4ad6)
 Func_4ae9: ; 4ae9 (1:4ae9)
 	call $5f4a
 	ld hl, $7b
-	call Func_2c1b
+	call InitTextPrinting_ProcessTextFromID
 	call $5f50
 	ld c, e
 	ld a, d
@@ -1621,7 +1621,7 @@ Func_4ae9: ; 4ae9 (1:4ae9)
 	ld hl, $7c
 .pkmn_in_play_area
 	dec d
-	call Func_2c1b
+	call InitTextPrinting_ProcessTextFromID
 	inc e
 	inc d
 	inc c
@@ -1632,7 +1632,7 @@ Func_4ae9: ; 4ae9 (1:4ae9)
 .asm_4b22
 	call $65b7
 	ld hl, $7e
-	call Func_2c1b
+	call InitTextPrinting_ProcessTextFromID
 	ret
 ; 0x4b2c
 
@@ -1865,7 +1865,7 @@ Func_4cd5: ; 4cd5 (1:4cd5)
 	ld a, BOXMSG_BENCH_POKEMON
 	call DrawDuelBoxMessage
 	ldtx hl, ChooseUpTo5BasicPkmnToPlaceOnBenchText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	ld a, $3
 	call DoPracticeDuelAction
 .asm_4d5f
@@ -2355,7 +2355,7 @@ Func_5256: ; 5256 (1:5256)
 	jp nz, $5382
 	ldtx de, DrMasonText
 	ldtx hl, Text01d9
-	call Func_2c62.asm_2c67
+	call PrintScrollableText_WithTextBoxLabel_NoWait
 	call YesOrNoMenu
 	jp $5382
 ; 0x5278
@@ -2373,7 +2373,7 @@ Func_5284: ; 5284 (1:5284)
 	call Func_52bc
 	ld a, $02
 	call BankswitchSRAM
-	ld de, $bc00
+	ld de, sCurrentDuelData
 	call $66ff
 	xor a
 	call BankswitchSRAM
@@ -2406,7 +2406,7 @@ Func_52b0: ; 52b0 (1:52b0)
 Func_52bc: ; 52bc (1:52bc)
 	push af
 	ldtx de, DrMasonText
-	call Func_2c62
+	call PrintScrollableText_WithTextBoxLabel
 	pop af
 	ret
 ; 0x52c5
@@ -3356,16 +3356,20 @@ LargeCardTileData: ; 5eb7 (1:5eb7)
 	db $ff
 ; 0x5f4a
 
-Func_5f4a: ; 5f4a (1:5f4a)
+; print lines of text with no separation between them
+SetNoLineSeparation: ; 5f4a (1:5f4a)
 	ld a, $01
-Func_5f4c: ; 5f4c (1:5f4c)
+;	fallthrough
+
+SetLineSeparation: ; 5f4c (1:5f4c)
 	ld [wLineSeparation], a
 	ret
 ; 0x5f50
 
-Func_5f50: ; 5f50 (1:5f50)
+; separate lines of text by an empty line
+SetOneLineSeparation: ; 5f50 (1:5f50)
 	xor a
-	jr Func_5f4c
+	jr SetLineSeparation
 ; 0x5f53
 
 	INCROM $5f53, $5fd9
@@ -3691,27 +3695,30 @@ Func_6510: ; 6510 (1:6510)
 	lb de, 1, 4
 	call InitTextPrinting
 	ld hl, wLoadedCard1Move1Name
-	call Func_2c20
+	call ProcessTextFromPointerToID_InitTextPrinting
 	lb de, 1, 6
 	ld hl, wLoadedCard1Move1Description
-	call Func_653e
+	call PrintMoveOrCardDescription
 	ret
 ; 0x653e
 
-Func_653e: ; 653e (1:653e)
-	call Func_5f4a
+; print the description of a move or of a trainer or energy card
+; x,y coordinates of where to start printing the text are given at de
+; don't separate lines of text
+PrintMoveOrCardDescription: ; 653e (1:653e)
+	call SetNoLineSeparation
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-	call Func_2c37
-	cp $07
-	jr c, .asm_654c
-	dec e
-.asm_654c
+	call CountLinesOfTextFromID
+	cp 7
+	jr c, .print
+	dec e ; move one line up to fit (assumes it will be enough)
+.print
 	ld a, 19
 	call InitTextPrintingInTextbox
-	call Func_2c29
-	call Func_5f50
+	call ProcessTextFromID
+	call SetOneLineSeparation
 	ret
 ; 0x6558
 
@@ -3818,7 +3825,7 @@ Func_6635: ; 6635 (1:6635)
 	call Func_5c33
 	lb de, 1, 4
 	ld hl, wLoadedMoveDescription
-	call Func_653e
+	call PrintMoveOrCardDescription
 	ret
 ; 0x666a
 
@@ -3831,17 +3838,17 @@ Func_666a: ; 666a (1:666a)
 
 Func_6673: ; 6673 (1:6673)
 	call EmptyScreen
-	call Func_5f4a
+	call SetNoLineSeparation
 	lb de, 1, 1
 	call InitTextPrinting
 	ld hl, wLoadedCard1Name
-	call Func_2c23
+	call ProcessTextFromPointerToID
 	ld a, 19
 	lb de, 1, 3
 	call InitTextPrintingInTextbox
 	ld hl, wLoadedCard1NonPokemonDescription
-	call Func_2c23
-	call Func_5f50
+	call ProcessTextFromPointerToID
+	call SetOneLineSeparation
 	ldtx hl, UsedText
 	call DrawWideTextBox_WaitForInput
 	ret
@@ -3935,7 +3942,7 @@ DuelDataToSave: ; 6729 (1:6729)
 
 Func_6785: ; 6785 (1:6785)
 	call EnableSRAM
-	ld hl, $bc00
+	ld hl, sCurrentDuelData
 	xor a
 	ld [hli], a
 	ld [hli], a
@@ -3944,23 +3951,24 @@ Func_6785: ; 6785 (1:6785)
 	ret
 ; 0x6793
 
-; loads player deck from SRAM to wPlayerDeck
+; loads a player deck (sDeck*Cards) from SRAM to wPlayerDeck
+; s0b700 determines which sDeck*Cards source (0-3)
 LoadPlayerDeck: ; 6793 (1:6793)
 	call EnableSRAM
-	ld a, [$b700]
+	ld a, [s0b700]
 	ld l, a
-	ld h, $54
+	ld h, sDeck2Cards - sDeck1Cards
 	call HtimesL
 	ld de, sDeck1Cards
 	add hl, de
 	ld de, wPlayerDeck
 	ld c, DECK_SIZE
-.next_card_loop
+.copy_cards_loop
 	ld a, [hli]
 	ld [de], a
 	inc de
 	dec c
-	jr nz, .next_card_loop
+	jr nz, .copy_cards_loop
 	call DisableSRAM
 	ret
 ; 0x67b2
@@ -3988,7 +3996,7 @@ AIMakeDecision: ; 67be (1:67be)
 .delay_loop
 	call DoFrame
 	ld a, [wVBlankCounter]
-	cp $3c
+	cp 60
 	jr c, .delay_loop
 
 .skip_delay
diff --git a/src/engine/bank02.asm b/src/engine/bank02.asm
index 7a9d33c..502af91 100644
--- a/src/engine/bank02.asm
+++ b/src/engine/bank02.asm
@@ -324,7 +324,7 @@ Func_8f8a: ; 8f8a (2:4f8a)
 
 Func_8f9d: ; 8f9d (2:4f9d)
 	call EnableSRAM
-	ld a, [$b700]
+	ld a, [s0b700]
 	call DisableSRAM
 	ld h, $3
 	ld l, a
@@ -338,7 +338,7 @@ Func_8f9d: ; 8f9d (2:4f9d)
 	call FillRectangle
 	ld a, [wceb1]
 	call EnableSRAM
-	ld [$b700], a
+	ld [s0b700], a
 	call DisableSRAM
 	call Func_9326
 	call GetPointerToDeckName
@@ -637,7 +637,7 @@ Func_9168: ; 9168 (2:5168)
 	ld [wceb5], a
 .asm_9214
 	call EnableSRAM
-	ld a, [$b700]
+	ld a, [s0b700]
 	ld c, a
 	ld b, $0
 	ld d, $2
@@ -657,7 +657,7 @@ Func_9168: ; 9168 (2:5168)
 	jr .asm_921f
 .asm_9234
 	ld a, c
-	ld [$b700], a
+	ld [s0b700], a
 	call DisableSRAM
 	call Func_9326
 	call EnableLCD
@@ -706,7 +706,7 @@ Func_926e: ; 926e (2:526e)
 .asm_929c
 	call InitTextPrinting
 	ldtx hl, NewDeckText
-	call Func_2c29
+	call ProcessTextFromID
 	scf
 	ret
 
@@ -746,7 +746,7 @@ Func_9314: ; 9314 (2:5314)
 
 Func_9326: ; 9326 (2:5326)
 	call EnableSRAM
-	ld a, [$b700]
+	ld a, [s0b700]
 	call DisableSRAM
 	ld h, 3
 	ld l, a
diff --git a/src/engine/bank03.asm b/src/engine/bank03.asm
index 7ad9a33..96d8694 100644
--- a/src/engine/bank03.asm
+++ b/src/engine/bank03.asm
@@ -326,7 +326,7 @@ Func_c268: ; c268 (3:4268)
 	ld l, a
 	or h
 	jr z, .asm_c27a
-	call Func_2c29
+	call ProcessTextFromID
 	pop hl
 	inc hl
 	inc hl
@@ -1063,7 +1063,7 @@ PC_c7ea: ; c7ea (3:47ea)
 	call $4915
 	call DoFrameIfLCDEnabled
 	ldtx hl, TurnedPCOnText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call $484e
 .asm_c801
 	ld a, $1
@@ -1121,7 +1121,7 @@ Func_c891: ; c891 (3:4891)
 	call Func_c241
 	call $4915
 	call DoFrameIfLCDEnabled
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	ret
 
 Func_c8ba: ; c8ba (3:48ba)
@@ -1716,7 +1716,7 @@ Func_ccdc: ; ccdc (3:4cdc)
 
 Func_cce4: ; cce4 (3:4ce4)
 	ld a, $1
-	ld [wcd9a], a
+	ld [wDefaultYesOrNo], a
 
 ; Asks the player a question then jumps if they answer yes
 OWScript_AskQuestionJump: ; cce9 (3:4ce9)
diff --git a/src/engine/bank04.asm b/src/engine/bank04.asm
index da12df8..ba48705 100644
--- a/src/engine/bank04.asm
+++ b/src/engine/bank04.asm
@@ -91,7 +91,7 @@ Medal_1029e: ; 1029e (4:429e)
 	cp $e0
 	jr nz, .asm_102e2
 	ldtx hl, WonTheMedalText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call Func_3c96
 	call ResumeSong
 	pop af
@@ -148,11 +148,11 @@ BoosterPack_1031b: ; 1031b (4:431b)
 	jr nz, .asm_10373
 	ldtx hl, AndAnotherBoosterPackText
 .asm_10373
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call Func_3c96
 	call ResumeSong
 	ldtx hl, CheckedCardsInBoosterPackText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call DisableLCD
 	call Func_1288c
 	call ZeroObjectPositions
@@ -445,7 +445,7 @@ Func_10f2e: ; 10f2e (4:4f2e)
 	ld a, [hli]
 	ld h, [hl]
 	ld l, a
-	call Func_2c29
+	call ProcessTextFromID
 	pop de
 	pop hl
 	ret
@@ -1511,7 +1511,7 @@ Func_1344d: ; 1344d (4:744d)
 	ld a, MUSIC_MEDAL
 	call PlaySong
 	ldtx hl, DefeatedFiveOpponentsText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call Func_3c96
 	call ResumeSong
 	ret
@@ -1533,7 +1533,7 @@ Func_13485: ; 13485 (4:7485)
 	ld a, MUSIC_MEDAL
 	call PlaySong
 	ldtx hl, ConsecutiveWinRecordIncreasedText
-	call Func_2c73
+	call PrintScrollableText_NoTextBoxLabel
 	call Func_3c96
 	call ResumeSong
 	ret
diff --git a/src/engine/home.asm b/src/engine/home.asm
index 05c6d21..8df064c 100644
--- a/src/engine/home.asm
+++ b/src/engine/home.asm
@@ -2933,7 +2933,7 @@ SerialRecv8Bytes: ; 0fe9 (0:0fe9)
 ; 0x100b
 
 ; save duel state to SRAM
-; called between each two-player turn, just after player draws card (bank 1 loaded)
+; called between each two-player turn, just after player draws card (ROM bank 1 loaded)
 SaveDuelStateToSRAM: ; 100b (0:100b)
 	ld a, $2
 	call BankswitchSRAM
@@ -2990,7 +2990,7 @@ SaveDuelStateToSRAM: ; 100b (0:100b)
 	call BankswitchSRAM
 	ret
 
-; copies the deck pointed to by de to wPlayerDeck or wOpponentDeck
+; copies the deck pointed to by de to wPlayerDeck or wOpponentDeck (depending on whose turn it is)
 CopyDeckData: ; 1072 (0:1072)
 	ld hl, wPlayerDeck
 	ldh a, [hWhoseTurn]
@@ -3038,7 +3038,7 @@ CopyDeckData: ; 1072 (0:1072)
 	ret
 ; 0x10aa
 
-; return, in register a, the amount of unclaimed prizes that the turn holder has left
+; return, in register a, the amount of prizes that the turn holder has not yet drawn
 CountPrizes: ; 10aa (0:10aa)
 	push hl
 	ld a, DUELVARS_PRIZES
@@ -3056,7 +3056,7 @@ CountPrizes: ; 10aa (0:10aa)
 ; 0x10bc
 
 ; shuffles the turn holder's deck
-; if less than 60 cards remain in the deck, make sure the rest are ignored
+; if less than 60 cards remain in the deck, it makes sure that the rest are ignored
 ShuffleDeck: ; 10bc (0:10bc)
 	ldh a, [hWhoseTurn]
 	ld h, a
@@ -3072,8 +3072,9 @@ ShuffleDeck: ; 10bc (0:10bc)
 	call ShuffleCards
 	ret
 
-; draw a card from the turn holder's deck, saving its location as CARD_LOCATION_JUST_DRAWN
-; returns carry if deck is empty, nc if a card was succesfully drawn
+; draw a card from the turn holder's deck, saving its location as CARD_LOCATION_JUST_DRAWN.
+; returns carry if deck is empty, nc if a card was succesfully drawn.
+; AddCardToHand is meant to be called next (unless this function returned carry).
 DrawCardFromDeck: ; 10cf (0:10cf)
 	push hl
 	ld a, DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK
@@ -3118,7 +3119,7 @@ ReturnCardToDeck: ; 10e8 (0:10e8)
 
 ; search a card in the turn holder's deck, extract it, and set its location to
 ; CARD_LOCATION_JUST_DRAWN. AddCardToHand is meant to be called next.
-; the card is identified by register a, which contains the deck index (0-59) of the card
+; the card is identified by register a, which contains the deck index (0-59) of the card.
 SearchCardInDeckAndAddToHand: ; 10fc (0:10fc)
 	push af
 	push hl
@@ -3206,7 +3207,7 @@ RemoveCardFromHand: ; 1139 (0:1139)
 	pop hl
 	jr .done_card
 .no_match
-	ld [de], a ; keep card in hand
+	ld [de], a ; keep any card that doesn't match in the player's hand
 	inc de
 .done_card
 	dec b
@@ -3231,7 +3232,7 @@ MoveHandCardToDiscardPile: ; 1160 (0:1160)
 	call RemoveCardFromHand
 ;	fallthrough
 
-; puts the card with the deck index (0-59) given in a into the discard pile
+; puts the turn holder's card with the deck index (0-59) given in a into the discard pile
 PutCardInDiscardPile: ; 116a (0:116a)
 	push af
 	push hl
@@ -3307,7 +3308,7 @@ PowersOf2:
 	db $01, $02, $04, $08, $10, $20, $40, $80
 ; 0x11bf
 
-; fill wDuelTempList with the turn holder's discard pile cards (their 0-59 deck index)
+; fill wDuelTempList with the turn holder's discard pile cards (their 0-59 deck indexes)
 ; return carry if the turn holder has no cards in the discard pile
 CreateDiscardPileCardList: ; 11bf (0:11bf)
 	ldh a, [hWhoseTurn]
@@ -3337,7 +3338,7 @@ CreateDiscardPileCardList: ; 11bf (0:11bf)
 	ret
 ; 0x11df
 
-; fill wDuelTempList with the turn holder's remaining deck cards (their 0-59 deck index)
+; fill wDuelTempList with the turn holder's remaining deck cards (their 0-59 deck indexes)
 ; return carry if the turn holder has no cards left in the deck
 CreateDeckCardList: ; 11df (0:11df)
 	ld a, DUELVARS_NUMBER_OF_CARDS_NOT_IN_DECK
@@ -3374,7 +3375,7 @@ CreateDeckCardList: ; 11df (0:11df)
 ; 0x120a
 
 ; fill wDuelTempList with the turn holder's energy cards
-; in the arena or in a bench slot (their 0-59 deck index).
+; in the arena or in a bench slot (their 0-59 deck indexes).
 ; if a == 0: search in CARD_LOCATION_ARENA
 ; if a != 0: search in CARD_LOCATION_BENCH_[A]
 ; return carry if no energy cards were found
@@ -3414,7 +3415,7 @@ CreateArenaOrBenchEnergyCardList: ; 120a (0:120a)
 	ret
 ; 0x123b
 
-; fill wDuelTempList with the turn holder's hand cards (their 0-59 deck index)
+; fill wDuelTempList with the turn holder's hand cards (their 0-59 deck indexes)
 ; return carry if the turn holder has no cards in hand
 CreateHandCardList: ; 123b (0:123b)
 	call FindLastCardInHand
@@ -3775,7 +3776,6 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 	ld e, a
 	call CheckIfCanEvolveInto
 	ret c ; return if it's not capable of evolving into the selected Pokemon
-
 	; place the evolved Pokemon card in the play area location of the pre-evolved Pokemon card
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
 	ld e, a
@@ -3788,7 +3788,6 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ldh a, [hTempCardIndex_ff98]
 	call PutHandCardInPlayArea
-
 	; update the Pokemon's HP with the difference
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
 	ld a, e ; derp
@@ -3812,7 +3811,6 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 	ld a, e
 	or a
 	call z, ResetStatusConditions
-
 	; set the new evolution stage of the card
 	ldh a, [hTempPlayAreaLocationOffset_ff9d]
 	add DUELVARS_ARENA_CARD_STAGE
@@ -3822,6 +3820,7 @@ EvolvePokemonCard: ; 13a2 (0:13a2)
 	or a
 	ret
 
+; never executed
 	scf
 	ret
 ; 0x13f7
@@ -3995,7 +3994,7 @@ PutHandPokemonCardInPlayArea: ; 1485 (0:1485)
 	ld [hl], a ; set card's evolution stage
 	ld a, e
 	or a
-	call z, ResetStatusConditions ; only call if Pokemon is being place in the arena
+	call z, ResetStatusConditions ; only call if Pokemon is being placed in the arena
 	ld a, e
 	or a
 	ret
@@ -4277,7 +4276,7 @@ CountCardIDInLocation: ; 15ef (0:15ef)
 	ret
 
 ; returns [[hWhoseTurn] << 8 + a] in a and in [hl]
-; i.e. variable a of the player whose turn it is
+; i.e. duelvar a of the player whose turn it is
 GetTurnDuelistVariable: ; 160b (0:160b)
 	ld l, a
 	ldh a, [hWhoseTurn]
@@ -4286,7 +4285,7 @@ GetTurnDuelistVariable: ; 160b (0:160b)
 	ret
 
 ; returns [([hWhoseTurn] ^ $1) << 8 + a] in a and in [hl]
-; i.e. variable a of the player whose turn it is not
+; i.e. duelvar a of the player whose turn it is not
 GetNonTurnDuelistVariable: ; 1611 (0:1611)
 	ld l, a
 	ldh a, [hWhoseTurn]
@@ -4315,7 +4314,7 @@ Func_161e: ; 161e (0:161e)
 	ld a, [wLoadedMoveCategory]
 	cp POKEMON_POWER
 	ret nz
-	call $6510
+	call Func_6510
 	ldh a, [hTempCardIndex_ff98]
 	call LoadCardDataToBuffer1_FromDeckIndex
 	ld hl, wLoadedCard1Name
@@ -4332,7 +4331,7 @@ Func_161e: ; 161e (0:161e)
 	ld a, $01 ; check only Muk
 	call CheckCannotUseDueToStatus_OnlyToxicGasIfANon0
 	jr nc, .use_pokemon_power
-	call $6510
+	call Func_6510
 	ldtx hl, UnableToUsePkmnPowerDueToToxicGasText
 	call DrawWideTextBox_WaitForInput
 	call ExchangeRNG
@@ -4565,7 +4564,7 @@ Func_17fb: ; 17fb (0:17fb)
 
 Func_1819: ; 1819 (0:1819)
 	push hl
-	call $6510
+	call Func_6510
 	pop hl
 
 Func_181e: ; 181e (0:181e)
@@ -6322,9 +6321,9 @@ Copy1bppTiles: ; 21ab (0:21ab)
 ; 0x21ba
 
 ; similar to ProcessText except it calls InitTextPrinting first
-; with register de as an argument to set hTextBGMap0Address.
+; with the first two bytes of hl being used to set hTextBGMap0Address.
 ; (the caller to ProcessText usually calls InitTextPrinting first)
-ProcessText_InitTextPrinting: ; 21ba (0:21ba)
+InitTextPrinting_ProcessText: ; 21ba (0:21ba)
 	push de
 	push bc
 	ld d, [hl]
@@ -6334,8 +6333,8 @@ ProcessText_InitTextPrinting: ; 21ba (0:21ba)
 	call InitTextPrinting
 	jr ProcessText.next_char
 
-; reads the characters from the text at hl processes them. loops until TX_END
-; is found. ignores TX_RAM1, TX_RAM2, and TX_RAM3 characters.
+; reads the characters from the text at hl processes them. loops until
+; TX_END is found. ignores TX_RAM1, TX_RAM2, and TX_RAM3 characters.
 ProcessText: ; 21c5 (0:21c5)
 	push de
 	push bc
@@ -7878,7 +7877,10 @@ CopyCardNameAndLevel: ; 29f5 (0:29f5)
 	ret
 ; 0x29fa
 
-Func_29fa: ; 29fa (0:29fa)
+; sets cursor parameters for navigating in a text box, but using
+; default values for the cursor tile and the tile behind it.
+; d,e: coordinates of the cursor
+SetCursorParametersForTextBox_Default: ; 29fa (0:29fa)
 	lb bc, SYM_CURSOR_R, SYM_SPACE ; cursor tile, tile behind cursor
 	call SetCursorParametersForTextBox
 ;	fallthrough
@@ -7901,6 +7903,9 @@ WaitForButtonAorB: ; 2a00 (0:2a00)
 	or a
 	ret
 
+; sets cursor parameters for navigating in a text box
+; d,e: coordinates of the cursor
+; b,c: tile numbers of the cursor and of the tile behind it
 SetCursorParametersForTextBox: ; 2a1a (0:2a1a)
 	xor a
 	ld hl, wCurMenuItem
@@ -7922,7 +7927,7 @@ SetCursorParametersForTextBox: ; 2a1a (0:2a1a)
 
 ; draw a 20x6 text box aligned to the bottom of the screen,
 ; print the text at hl without letter delay, and wait for A or B pressed
-Func_2a30: ; 2a30 (0:2a30)
+DrawWideTextBox_PrintTextNoDelay_Wait: ; 2a30 (0:2a30)
 	call DrawWideTextBox_PrintTextNoDelay
 	jp WaitForWideTextBoxInput
 ; 0x2a36
@@ -7933,7 +7938,7 @@ DrawWideTextBox_PrintTextNoDelay: ; 2a36 (0:2a36)
 	push hl
 	call DrawWideTextBox
 	ld a, 19
-	jr Func_2a44
+	jr DrawTextBox_PrintTextNoDelay
 
 ; draw a 12x6 text box aligned to the bottom left of the screen
 ; and print the text at hl without letter delay
@@ -7943,7 +7948,7 @@ DrawNarrowTextBox_PrintTextNoDelay: ; 2a3e (0:2a3e)
 	ld a, 11
 ;	fallthrough
 
-Func_2a44: ; 2a44 (0:2a44)
+DrawTextBox_PrintTextNoDelay: ; 2a44 (0:2a44)
 	lb de, 1, 14
 	call AdjustCoordinatesForBGScroll
 	call InitTextPrintingInTextbox
@@ -8048,16 +8053,18 @@ TwoItemHorizontalMenu: ; 2ad0 (0:2ad0)
 	jp HandleYesOrNoMenu.refresh_menu
 ; 0x2aeb
 
-Func_2aeb: ; 2aeb (0:2aeb)
+YesOrNoMenuWithText_SetCursorToYes: ; 2aeb (0:2aeb)
 	ld a, $01
-	ld [wcd9a], a
+	ld [wDefaultYesOrNo], a
 ;	fallthrough
 
 ; display a yes / no menu with custom text provided in hl and handle input
+; wDefaultYesOrNo determines whether the cursor initially points to YES or to NO
 ; returns carry if "no" selected
 YesOrNoMenuWithText: ; 2af0 (0:2af0)
 	call DrawWideTextBox_PrintText
 ;	fallthrough
+
 YesOrNoMenu: ; 2af3 (0:2af3)
 	lb de, 7, 16 ; x, y
 	call PrintYesOrNoItems
@@ -8070,12 +8077,13 @@ YesOrNoMenuWithText_LeftAligned: ; 2afe (0:2afe)
 	call PrintYesOrNoItems
 	lb de, 2, 16 ; x, y
 ;	fallthrough
+
 HandleYesOrNoMenu:
 	ld a, d
 	ld [wLeftmostItemCursorX], a
 	lb bc, SYM_CURSOR_R, SYM_SPACE ; cursor tile, tile behind cursor
 	call SetCursorParametersForTextBox
-	ld a, [wcd9a]
+	ld a, [wDefaultYesOrNo]
 	ld [wCurMenuItem], a
 	call EnableLCD
 	jr .refresh_menu
@@ -8114,11 +8122,11 @@ HandleYesOrNoMenu:
 	or a
 	jr nz, .no
 ;.yes
-	ld [wcd9a], a ; 0
+	ld [wDefaultYesOrNo], a ; 0
 	ret
 .no
 	xor a
-	ld [wcd9a], a ; 0
+	ld [wDefaultYesOrNo], a ; 0
 	ld a, 1
 	ldh [hCurMenuItem], a
 	scf
@@ -8128,14 +8136,14 @@ HandleYesOrNoMenu:
 PrintYesOrNoItems: ; 2b66 (0:2b66)
 	call AdjustCoordinatesForBGScroll
 	ldtx hl, YesOrNoText
-	call Func_2c1b
+	call InitTextPrinting_ProcessTextFromID
 	ret
 ; 0x2b70
 
-Func_2b70: ; 2b70 (0:2b70)
-	ld a, BANK(ContinueDuel)
+ContinueDuel: ; 2b70 (0:2b70)
+	ld a, BANK(_ContinueDuel)
 	call BankswitchHome
-	jp ContinueDuel
+	jp _ContinueDuel
 ; 0x2b78
 
 ; loads opponent deck to wOpponentDeck
@@ -8255,26 +8263,37 @@ PlaceTextItems: ; 2c08 (0:2c08)
 	inc hl ; hl = text id
 	call InitTextPrinting
 	push hl
-	call Func_2c23
+	call ProcessTextFromPointerToID
 	pop hl
 	inc hl
 	inc hl
 	jr PlaceTextItems ; do next item
 
-Func_2c1b: ; 2c1b (0:2c1b)
+; like ProcessTextFromID, except it calls InitTextPrinting first
+InitTextPrinting_ProcessTextFromID: ; 2c1b (0:2c1b)
 	call InitTextPrinting
-	jr Func_2c29
+	jr ProcessTextFromID
 
-Func_2c20: ; 2c20 (0:2c20)
+; like ProcessTextFromPointerToID, except it calls InitTextPrinting first
+ProcessTextFromPointerToID_InitTextPrinting: ; 2c20 (0:2c20)
 	call InitTextPrinting
-Func_2c23: ; 2c23 (0:2c23)
+;	fallthrough
+
+; like ProcessTextFromID below, except a memory address containing a text ID is
+; provided in hl rather than the text ID directly.
+ProcessTextFromPointerToID: ; 2c23 (0:2c23)
 	ld a, [hli]
 	or [hl]
 	ret z
 	ld a, [hld]
 	ld l, [hl]
 	ld h, a
-Func_2c29: ; 2c29 (0:2c29)
+;	fallthrough
+
+; given the ID of a text in hl, reads the characters from it processes them.
+; loops until TX_END is found. ignores TX_RAM1, TX_RAM2, and TX_RAM3 characters.
+; restores original ROM bank before returning.
+ProcessTextFromID: ; 2c29 (0:2c29)
 	ldh a, [hBankROM]
 	push af
 	call GetTextOffsetFromTextID
@@ -8284,7 +8303,9 @@ Func_2c29: ; 2c29 (0:2c29)
 	ret
 ; 0x2c37
 
-Func_2c37: ; 2c37 (0:2c37)
+; return, in a, the number of lines of the text given in hl as an ID
+; this is calculated by counting the amount of '\n' characters and adding 1 to the result
+CountLinesOfTextFromID: ; 2c37 (0:2c37)
 	push hl
 	push de
 	push bc
@@ -8318,10 +8339,13 @@ Func_2c37: ; 2c37 (0:2c37)
 	ret
 ; 0x2c62
 
-Func_2c62: ; 2c62 (0:2c62)
-	call .asm_2c67
+; call PrintScrollableText with text box label, then wait for the
+; player to press A or B to advance the printed text
+PrintScrollableText_WithTextBoxLabel: ; 2c62 (0:2c62)
+	call PrintScrollableText_WithTextBoxLabel_NoWait
 	jr WaitForPlayerToAdvanceText
-.asm_2c67
+
+PrintScrollableText_WithTextBoxLabel_NoWait: ; 2c67 (0:2c67)
 	push hl
 	ld hl, wTextBoxLabel
 	ld [hl], e
@@ -8331,12 +8355,15 @@ Func_2c62: ; 2c62 (0:2c62)
 	ld a, $01
 	jr PrintScrollableText
 
-Func_2c73: ; 2c73 (0:2c73)
+; call PrintScrollableText with no text box label, then wait for the
+; player to press A or B to advance the printed text
+PrintScrollableText_NoTextBoxLabel: ; 2c73 (0:2c73)
 	xor a
 	call PrintScrollableText
+;	fallthrough
 
-; when a text box is full, prompt the player to press A or B
-; in order to clear the text and print the next lines.
+; when a text box is full or the text is over, prompt the player to
+; press A or B in order to clear the text and print the next lines.
 WaitForPlayerToAdvanceText: ; 2c77 (0:2c77)
 	lb bc, SYM_CURSOR_D, SYM_BOX_BOTTOM ; cursor tile, tile behind cursor
 	lb de, 18, 17 ; x, y
@@ -8344,16 +8371,17 @@ WaitForPlayerToAdvanceText: ; 2c77 (0:2c77)
 	call WaitForButtonAorB
 	ret
 
-; prints text with id at hl, with letter delay, in a textbox area.
-; unlike PrintText, PrintScrollableText supports scrollable text, and prompts
-; the user to press A or B to advance the page or close the text.
-; used mostly for overworld NPC text.
+; draws a text box, and prints the text with id at hl, with letter delay. unlike PrintText,
+; PrintScrollableText also supports scrollable text, and prompts the user to press A or B
+; to advance the page or close the text. register a determines whether the textbox is
+; labeled or not. if labeled, the text id of the label is provided in wTextBoxLabel.
+; PrintScrollableText is used mostly for overworld NPC text.
 PrintScrollableText: ; 2c84 (0:2c84)
 	ld [wIsTextBoxLabeled], a
 	ldh a, [hBankROM]
 	push af
 	call GetTextOffsetFromTextID
-	call Func_2d15
+	call DrawTextReadyLabeledOrRegularTextBox
 	call ResetTxRam_WriteToTextHeader
 .print_char_loop
 	ld a, [wTextSpeed]
@@ -8383,7 +8411,7 @@ PrintScrollableText: ; 2c84 (0:2c84)
 	jr c, .print_char_loop
 	; two lines of text already printed, so need to advance text
 	call WaitForPlayerToAdvanceText
-	call Func_2d15
+	call DrawTextReadyLabeledOrRegularTextBox
 	jr .print_char_loop
 .asm_2cc3
 	pop af
@@ -8456,7 +8484,10 @@ GetPointerToTextHeader: ; 2d06 (0:2d06)
 	add hl, de
 	ret
 
-Func_2d15: ; 2d15 (0:2d15)
+; draws a wide text box with or without label depending on wIsTextBoxLabeled
+; if labeled, the label's text ID is provided in wTextBoxLabel
+; calls InitTextPrintingInTextbox after drawing the text box
+DrawTextReadyLabeledOrRegularTextBox: ; 2d15 (0:2d15)
 	push hl
 	lb de, 0, 12
 	lb bc, 20, 6
diff --git a/src/sram.asm b/src/sram.asm
index 69b49c6..9a8d752 100644
--- a/src/sram.asm
+++ b/src/sram.asm
@@ -37,6 +37,10 @@ s0a350:: ds DECK_NAME_SIZE + DECK_SIZE ; a350
 s0a3a4:: ds DECK_NAME_SIZE + DECK_SIZE ; a3a4
 s0a3f8:: ds DECK_NAME_SIZE + DECK_SIZE ; a3f8
 
+	ds $12b4
+
+s0b700:: ds $1
+
 SECTION "SRAM1", SRAM
 
 SECTION "SRAM2", SRAM
diff --git a/src/wram.asm b/src/wram.asm
index e82ad32..34ccd9f 100644
--- a/src/wram.asm
+++ b/src/wram.asm
@@ -1051,7 +1051,9 @@ wLeftmostItemCursorX:: ; cd98
 wRefreshMenuCursorSFX:: ; cd99
 	ds $1
 
-wcd9a:: ; cd9a
+; when printing a YES/NO menu, whether the cursor is
+; initialized to the YES ($01) or to the NO ($00) item
+wDefaultYesOrNo:: ; cd9a
 	ds $1
 
 ; used in _CopyCardNameAndLevel to keep track of the remaining space to copy the text