Add comments associating constants with data, and identify some more data

23 files changed, 81 insertions, 13 deletions

diff --git a/constants/battle_constants.asm b/constants/battle_constants.asm
index 4a113ca0..99d371b2 100644
--- a/constants/battle_constants.asm
+++ b/constants/battle_constants.asm
@@ -8,7 +8,7 @@ NUM_DVS       EQU 2
 ; D733 flags
 BIT_TEST_BATTLE EQU 0
 
-; battle type constants
+; battle type constants (wBattleType values)
 	const_def
 	const BATTLE_TYPE_NORMAL  ; 0
 	const BATTLE_TYPE_OLD_MAN ; 1
@@ -43,7 +43,7 @@ MAX_STAT_VALUE EQU 999
 ATKDEFDV_TRAINER EQU $98
 SPDSPCDV_TRAINER EQU $88
 
-; volatile statuses 1
+; wPlayerBattleStatus1 or wEnemyBattleStatus1 bit flags
 	const_def
 	const STORING_ENERGY           ; 0 ; Bide
 	const THRASHING_ABOUT          ; 1 ; e.g. Thrash
@@ -54,7 +54,7 @@ SPDSPCDV_TRAINER EQU $88
 	const INVULNERABLE             ; 6 ; charging up Fly/Dig
 	const CONFUSED                 ; 7
 
-; volatile statuses 2
+; wPlayerBattleStatus2 or wEnemyBattleStatus2 bit flags
 	const_def
 	const USING_X_ACCURACY    ; 0
 	const PROTECTED_BY_MIST   ; 1
@@ -65,7 +65,7 @@ SPDSPCDV_TRAINER EQU $88
 	const USING_RAGE          ; 6
 	const SEEDED              ; 7
 
-; volatile statuses 3
+; wPlayerBattleStatus3 or wEnemyBattleStatus3 bit flags
 	const_def
 	const BADLY_POISONED      ; 0
 	const HAS_LIGHT_SCREEN_UP ; 1
diff --git a/constants/credits_constants.asm b/constants/credits_constants.asm
index 8ad9114b..dcf782ef 100644
--- a/constants/credits_constants.asm
+++ b/constants/credits_constants.asm
@@ -1,3 +1,4 @@
+; CreditsTextPointers indexes (see data/credits/credits_text.asm)
 	const_def
 	const CRED_VERSION        ; $00
 	const CRED_TAJIRI         ; $01
diff --git a/constants/event_constants.asm b/constants/event_constants.asm
index 29c2e537..4f169880 100755
--- a/constants/event_constants.asm
+++ b/constants/event_constants.asm
@@ -1,3 +1,5 @@
+; wEventFlags bit flags
+
 ; Pallet Town events
 	const_def
 	const EVENT_FOLLOWED_OAK_INTO_LAB
diff --git a/constants/gfx_constants.asm b/constants/gfx_constants.asm
index d6d162c7..912e5835 100644
--- a/constants/gfx_constants.asm
+++ b/constants/gfx_constants.asm
@@ -31,6 +31,7 @@ REDRAW_COL EQU 1
 REDRAW_ROW EQU 2
 
 ; tile list ids
+; TileIDListPointerTable indexes (see data/tilemaps.asm)
 	const_def
 	const TILEMAP_MON_PIC
 	const TILEMAP_SLIDE_DOWN_MON_PIC_7X5
diff --git a/constants/hide_show_constants.asm b/constants/hide_show_constants.asm
index 21c83644..82e80bae 100755
--- a/constants/hide_show_constants.asm
+++ b/constants/hide_show_constants.asm
@@ -1,6 +1,7 @@
 HIDE EQU $11
 SHOW EQU $15
 
+; MissableObjects indexes (see data/maps/hide_show_data.asm)
 ; this is a list of the sprites that can be enabled/disabled during the game
 ; sprites marked with an X are constants that are never used
 ; because those sprites are not (de)activated in a map's script
diff --git a/constants/icon_constants.asm b/constants/icon_constants.asm
index b96c516d..14202da3 100644
--- a/constants/icon_constants.asm
+++ b/constants/icon_constants.asm
@@ -1,4 +1,5 @@
 ; party menu icons
+; used in MonPartySpritePointers (see data/icon_pointers.asm)
 	const_def
 	const ICON_MON       ; $0
 	const ICON_BALL      ; $1
@@ -10,3 +11,7 @@
 	const ICON_GRASS     ; $7
 	const ICON_SNAKE     ; $8
 	const ICON_QUADRUPED ; $9
+
+ICON_TRADEBUBBLE EQU $e
+
+ICONOFFSET EQU $40 ; difference between alternating icon frames' tile IDs
diff --git a/constants/input_constants.asm b/constants/input_constants.asm
index e5bc2a7b..7984d5a9 100644
--- a/constants/input_constants.asm
+++ b/constants/input_constants.asm
@@ -1,3 +1,4 @@
+; joypad buttons
 	const_def
 	const BIT_A_BUTTON
 	const BIT_B_BUTTON
diff --git a/constants/item_constants.asm b/constants/item_constants.asm
index c34269a8..67416600 100755
--- a/constants/item_constants.asm
+++ b/constants/item_constants.asm
@@ -1,3 +1,10 @@
+; item ids
+; indexes for:
+; - ItemNames (see data/items/names.asm)
+; - ItemPrices (see data/items/prices.asm)
+; - TechnicalMachinePrices (see data/items/tm_prices.asm)
+; - KeyItemBitfield (see data/items/key_items.asm)
+; - ItemUsePtrTable (see engine/items/item_effects.asm)
 	const_def
 	const NO_ITEM       ; $00
 	const MASTER_BALL   ; $01
diff --git a/constants/list_constants.asm b/constants/list_constants.asm
index 380df21c..840856df 100755
--- a/constants/list_constants.asm
+++ b/constants/list_constants.asm
@@ -6,6 +6,7 @@
 	const ITEMLISTMENU       ; $03 ; Start menu Item menu / Pokemart sell menu
 	const SPECIALLISTMENU    ; $04 ; list of special "items" e.g. floor list in elevators / list of badges
 
+; NamePointers indexes (see home/names2.asm)
 	const_def 1
 	const MONSTER_NAME  ; 1
 	const MOVE_NAME     ; 2
diff --git a/constants/map_constants.asm b/constants/map_constants.asm
index 6c7d8d48..b6ec77d5 100644
--- a/constants/map_constants.asm
+++ b/constants/map_constants.asm
@@ -4,6 +4,15 @@ mapconst: MACRO
 \1_WIDTH EQU \3
 ENDM
 
+; map ids
+; indexes for:
+; - MapHeaderBanks (see data/maps/map_header_banks.asm)
+; - MapHeaderPointers (see data/maps/map_header_pointers.asm)
+; - MapSongBanks (see data/maps/songs.asm)
+; - MapHSPointers (see data/maps/hide_show_data.asm)
+; - MapSpriteSets (see data/maps/sprite_sets.asm)
+; - ExternalMapEntries (see data/maps/town_map_entries.asm)
+; Each map also has associated data in maps.asm.
 	const_def
 	mapconst PALLET_TOWN,                    9, 10 ; $00
 	mapconst VIRIDIAN_CITY,                 18, 20 ; $01
diff --git a/constants/menu_constants.asm b/constants/menu_constants.asm
index 3a601dc2..a53adfdc 100644
--- a/constants/menu_constants.asm
+++ b/constants/menu_constants.asm
@@ -5,11 +5,11 @@ PC_ITEM_CAPACITY  EQU 50
 	const_def 1
 	const MESSAGE_BOX                       ; $01
 	const_skip                              ; $02
-	const_skip                              ; $03
+	const MENU_TEMPLATE_03                  ; $03 unused
 	const FIELD_MOVE_MON_MENU               ; $04
 	const JP_MOCHIMONO_MENU_TEMPLATE        ; $05
 	const USE_TOSS_MENU_TEMPLATE            ; $06
-	const_skip                              ; $07
+	const MENU_TEMPLATE_07                  ; $07 unused
 	const JP_SAVE_MESSAGE_MENU_TEMPLATE     ; $08
 	const JP_SPEED_OPTIONS_MENU_TEMPLATE    ; $09
 	const_skip                              ; $0a
@@ -18,7 +18,7 @@ PC_ITEM_CAPACITY  EQU 50
 	const LIST_MENU_BOX                     ; $0d
 	const BUY_SELL_QUIT_MENU_TEMPLATE       ; $0e
 	const MONEY_BOX_TEMPLATE                ; $0f
-	const_skip                              ; $10
+	const MENU_TEMPLATE_10                  ; $10 unused
 	const MON_SPRITE_POPUP                  ; $11
 	const JP_AH_MENU_TEMPLATE               ; $12
 	const MONEY_BOX                         ; $13
@@ -32,6 +32,7 @@ PC_ITEM_CAPACITY  EQU 50
 	const SAFARI_BATTLE_MENU_TEMPLATE       ; $1b
 
 ; two option menu constants
+; TwoOptionMenuStrings indexes (see data/yes_no_menu_strings.asm)
 	const_def
 	const YES_NO_MENU       ; 0
 	const NORTH_WEST_MENU   ; 1
@@ -58,7 +59,7 @@ CHOSE_SECOND_ITEM EQU 2
 	const PARTY_TO_DAYCARE ; 3
 
 ; party menu types
-; PartyMenuMessagePointers indexes
+; PartyMenuMessagePointers indexes (see engine/menus/party_menu.asm)
 	const_def
 	const NORMAL_PARTY_MENU    ; $00
 	const USE_ITEM_PARTY_MENU  ; $01
@@ -67,7 +68,7 @@ CHOSE_SECOND_ITEM EQU 2
 	const SWAP_MONS_PARTY_MENU ; $04
 	const EVO_STONE_PARTY_MENU ; $05
 ; party menu message IDs
-; PartyMenuItemUseMessagePointers indexes
+; PartyMenuItemUseMessagePointers indexes (see engine/menus/party_menu.asm)
 	const_next $F0
 FIRST_PARTY_MENU_TEXT_ID EQU const_value
 	const ANTIDOTE_MSG         ; $F0
diff --git a/constants/move_animation_constants.asm b/constants/move_animation_constants.asm
index 6f3839d6..f7617544 100644
--- a/constants/move_animation_constants.asm
+++ b/constants/move_animation_constants.asm
@@ -1,4 +1,5 @@
 ; special effects that are part of move animations
+; SpecialEffectPointers associates them with effect routines (see data/battle_anims/special_effect_pointers.asm)
 	const_def $C0
 FIRST_SE_ID EQU const_value
 	const_skip $18
@@ -43,6 +44,7 @@ FIRST_SE_ID EQU const_value
 	const SE_DARK_SCREEN_FLASH         ; $FE used in Cut/Take Down/etc.
 
 ; subanimations that are part of move animations
+; SubanimationPointers indexes (see data/battle_anims/subanimations.asm)
 	const_def
 	const SUBANIM_00
 	const SUBANIM_01
@@ -141,6 +143,7 @@ FIRST_SE_ID EQU const_value
 	const SUBANIMTYPE_ENEMY
 
 ; frame blocks that are part of subanimations
+; FrameBlockPointers indexes (see data/battle_anims/frame_blocks.asm)
 	const_def
 	const FRAMEBLOCK_00
 	const FRAMEBLOCK_01
@@ -266,6 +269,7 @@ FIRST_SE_ID EQU const_value
 	const FRAMEBLOCK_79
 
 ; base coordinates that are part of subanimations
+; FrameBlockBaseCoords indexes (see data/battle_anims/base_coords.asm)
 	const_def
 	const BASECOORD_00
 	const BASECOORD_01
diff --git a/constants/move_constants.asm b/constants/move_constants.asm
index 5dd06a41..ecc28078 100644
--- a/constants/move_constants.asm
+++ b/constants/move_constants.asm
@@ -1,3 +1,9 @@
+; move ids
+; indexes for:
+; - Moves (see data/moves/moves.asm)
+; - MoveNames (see data/moves/names.asm)
+; - AttackAnimationPointers (see data/moves/animations.asm)
+; - MoveSoundTable (see data/moves/sfx.asm)
 	const_def
 	const NO_MOVE      ; 00
 	const POUND        ; 01
diff --git a/constants/move_effect_constants.asm b/constants/move_effect_constants.asm
index 8872ac3e..5b81300f 100644
--- a/constants/move_effect_constants.asm
+++ b/constants/move_effect_constants.asm
@@ -1,8 +1,8 @@
-; tentative move effect constants
 ; {stat}_(UP|DOWN)(1|2) means that the move raises the user's (or lowers the target's) corresponding stat modifier by 1 (or 2) stages
-; {status condition}_side_effect means that the move has a side chance of causing that condition
-; {status condition}_effect means that the move causes the status condition every time it hits the target
+; {status condition}_SIDE_EFFECT means that the move has a side chance of causing that condition
+; {status condition}_EFFECT means that the move causes the status condition every time it hits the target
 
+; MoveEffectPointerTable indexes (see data/moves/effects_pointers.asm)
 	const_def
 	const NO_ADDITIONAL_EFFECT       ; $00
 	const EFFECT_01                  ; $01 unused
diff --git a/constants/music_constants.asm b/constants/music_constants.asm
index 3f3f111e..fcca9005 100644
--- a/constants/music_constants.asm
+++ b/constants/music_constants.asm
@@ -1,4 +1,5 @@
 ; Song ids are calculated by address to save space.
+; SFX_Headers_(1|2|3) indexes (see audio/headers/*.asm)
 
 music_const: MACRO
 \1 EQUS "((\2 - SFX_Headers_1) / 3)"
diff --git a/constants/palette_constants.asm b/constants/palette_constants.asm
index c0c397ee..fd5dd24b 100755
--- a/constants/palette_constants.asm
+++ b/constants/palette_constants.asm
@@ -6,6 +6,7 @@
 	const BLACK
 
 ; pal/blk packets
+; SetPalFunctions indexes (see engine/gfx/palettes.asm)
 	const_def
 	const SET_PAL_BATTLE_BLACK         ; $00
 	const SET_PAL_BATTLE               ; $01
@@ -26,6 +27,7 @@ SET_PAL_PARTY_MENU_HP_BARS EQU $fc
 SET_PAL_DEFAULT EQU $ff
 
 ; sgb palettes
+; SuperPalettes indexes (see data/sgb/sgb_palettes.asm)
 	const_def
 	const PAL_ROUTE     ; $00
 	const PAL_PALLET    ; $01
diff --git a/constants/pokedex_constants.asm b/constants/pokedex_constants.asm
index e462586e..a805b261 100644
--- a/constants/pokedex_constants.asm
+++ b/constants/pokedex_constants.asm
@@ -1,3 +1,8 @@
+; pokedex ids
+; indexes for:
+; - BaseStats (see data/pokemon/base_stats.asm)
+; - MonPartyData (see data/pokemon/menu_icons.asm)
+; - MonsterPalettes (see data/pokemon/palettes.asm)
 	const_def 1
 	const DEX_BULBASAUR  ; 1
 	const DEX_IVYSAUR    ; 2
diff --git a/constants/pokemon_constants.asm b/constants/pokemon_constants.asm
index 349e9359..5a91f0f8 100644
--- a/constants/pokemon_constants.asm
+++ b/constants/pokemon_constants.asm
@@ -1,3 +1,10 @@
+; pokemon ids
+; indexes for:
+; - MonsterNames (see data/pokemon/names.asm)
+; - EvosMovesPointerTable (see data/pokemon/evos_moves.asm)
+; - CryData (see data/pokemon/cries.asm)
+; - PokedexOrder (see data/pokemon/dex_order.asm)
+; - PokedexEntryPointers (see data/pokemon/dex_entries.asm)
 	const_def
 	const NO_MON       ; $00
 	const RHYDON       ; $01
diff --git a/constants/script_constants.asm b/constants/script_constants.asm
index 018fb7f2..2b2a9b14 100644
--- a/constants/script_constants.asm
+++ b/constants/script_constants.asm
@@ -1,4 +1,4 @@
-; emotion bubbles
+; EmotionBubblesPointerTable indexes (see engine/overworld/emotion_bubbles.asm)
 	const_def
 	const EXCLAMATION_BUBBLE ; 0
 	const QUESTION_BUBBLE    ; 1
@@ -13,6 +13,7 @@ SLOTSBIRD   EQU $1210
 SLOTSMOUSE  EQU $1614
 
 ; in game trades
+; TradeMons indexes (see data/events/trades.asm)
 	const_def
 	const TRADE_FOR_TERRY
 	const TRADE_FOR_MARCEL
@@ -26,6 +27,7 @@ SLOTSMOUSE  EQU $1614
 	const TRADE_FOR_SPOT
 
 ; in game trade dialog sets
+; InGameTradeTextPointers indexes (see engine/events/in_game_trades.asm)
 	const_def
 	const TRADE_DIALOGSET_CASUAL
 	const TRADE_DIALOGSET_POLITE
diff --git a/constants/sprite_constants.asm b/constants/sprite_constants.asm
index dc8352de..a4354996 100755
--- a/constants/sprite_constants.asm
+++ b/constants/sprite_constants.asm
@@ -1,4 +1,5 @@
 ; overworld sprites
+; SpriteSheetPointerTable indexes (see data/sprites/sprites.asm)
 	const_def
 	const SPRITE_NONE                    ; $00
 	const SPRITE_RED                     ; $01
diff --git a/constants/tileset_constants.asm b/constants/tileset_constants.asm
index 33d59fcb..95473081 100644
--- a/constants/tileset_constants.asm
+++ b/constants/tileset_constants.asm
@@ -1,3 +1,5 @@
+; tileset ids
+; Tilesets indexes (see data/tilesets/tileset_headers.asm)
 	const_def
 	const OVERWORLD    ; 0
 	const REDS_HOUSE_1 ; 1
diff --git a/constants/trainer_constants.asm b/constants/trainer_constants.asm
index 8e29b715..6fdc5d4e 100755
--- a/constants/trainer_constants.asm
+++ b/constants/trainer_constants.asm
@@ -5,6 +5,14 @@ trainer_const: MACRO
 OPP_\1 EQU OPP_ID_OFFSET + \1
 ENDM
 
+; trainer class ids
+; indexes for:
+; - TrainerNames (see data/trainers/names.asm)
+; - TrainerNamePointers (see data/trainers/name_pointers.asm)
+; - TrainerDataPointers (see data/trainers/parties.asm)
+; - TrainerPicAndMoneyPointers (see data/trainers/pic_pointers_money.asm)
+; - TrainerAIPointers (see data/trainers/ai_pointers.asm)
+; - TrainerClassMoveChoiceModifications (see data/trainers/move_choices.asm)
 	const_def
 	trainer_const NOBODY         ; $00
 	trainer_const YOUNGSTER      ; $01
diff --git a/constants/type_constants.asm b/constants/type_constants.asm
index 11fb3321..6ae3408d 100755
--- a/constants/type_constants.asm
+++ b/constants/type_constants.asm
@@ -1,3 +1,4 @@
+; TypeNames indexes (see data/types/names.asm)
 	const_def
 
 PHYSICAL EQU const_value