Clean up bugs commented in the source code (#912)

Co-authored-by: Rangi <remy.oukaour+rangi42@gmail.com>

engine/overworld/events.asm

@@ -554,7 +554,7 @@ TryObjectEvent:
 	ld a, [hl]
 	and %00001111
 
-; Bug: If IsInArray returns nc, data at bc will be executed as code.
+; BUG: TryObjectEvent arbitrary code execution (see docs/bugs_and_glitches.md)
 	push bc
 	ld de, 3
 	ld hl, ObjectEventTypeArray
@@ -569,7 +569,6 @@ TryObjectEvent:
 	jp hl
 
 .nope
-	; pop bc
 	xor a
 	ret
 

engine/overworld/map_objects.asm

@@ -2689,7 +2689,7 @@ ResetObject:
 	add hl, bc
 	ld a, [hl]
 	cp -1
-	jp z, .set_standing ; a jr would have been appropriate here
+	jp z, .set_standing
 	push bc
 	call GetMapObject
 	ld hl, MAPOBJECT_MOVEMENT

engine/overworld/npc_movement.asm

@@ -4,10 +4,10 @@ CanObjectMoveInDirection:
 	bit SWIMMING_F, [hl]
 	jr z, .not_swimming
 
+; BUG: Swimming NPCs aren't limited by their movement radius (see docs/bugs_and_glitches.md)
 	ld hl, OBJECT_FLAGS1
 	add hl, bc
-	bit NOCLIP_TILES_F, [hl] ; lost, uncomment next line to fix
-	; jr nz, .noclip_tiles
+	bit NOCLIP_TILES_F, [hl]
 	push hl
 	push bc
 	call WillObjectBumpIntoLand

engine/overworld/overworld.asm

@@ -346,8 +346,7 @@ AddSpriteGFX:
 	ret
 
 LoadSpriteGFX:
-; Bug: b is not preserved, so it's useless as a next count.
-; Uncomment the lines below to fix.
+; BUG: LoadSpriteGFX does not limit the capacity of UsedSprites (see docs/bugs_and_glitches.md)
 
 	ld hl, wUsedSprites
 	ld b, SPRITE_GFX_LIST_CAPACITY
@@ -366,9 +365,7 @@ LoadSpriteGFX:
 	ret
 
 .LoadSprite:
-	; push bc
 	call GetSprite
-	; pop bc
 	ld a, l
 	ret
 

engine/overworld/player_movement.asm

@@ -391,14 +391,9 @@ DoPlayerMovement::
 	db FACE_UP | FACE_LEFT    ; COLL_HOP_UP_LEFT
 
 .CheckWarp:
-; Bug: Since no case is made for STANDING here, it will check
-; [.EdgeWarps + $ff]. This resolves to $3e.
-; This causes wWalkingIntoEdgeWarp to be nonzero when standing on tile $3e,
-; making bumps silent.
+; BUG: No bump noise if standing on tile $3E (see docs/bugs_and_glitches.md)
 
 	ld a, [wWalkingDirection]
-	; cp STANDING
-	; jr z, .not_warp
 	ld e, a
 	ld d, 0
 	ld hl, .EdgeWarps
@@ -410,7 +405,6 @@ DoPlayerMovement::
 	ld a, TRUE
 	ld [wWalkingIntoEdgeWarp], a
 	ld a, [wWalkingDirection]
-	; This is in the wrong place.
 	cp STANDING
 	jr z, .not_warp
 

engine/overworld/scripting.asm

@@ -1240,11 +1240,7 @@ Script_memcall:
 	; fallthrough
 
 ScriptCall:
-; Bug: The script stack has a capacity of 5 scripts, yet there is
-; nothing to stop you from pushing a sixth script.  The high part
-; of the script address can then be overwritten by modifications
-; to wScriptDelay, causing the script to return to the rst/interrupt
-; space.
+; BUG: ScriptCall can overflow wScriptStack and crash (see docs/bugs_and_glitches.md)
 
 	push de
 	ld hl, wScriptStackSize

engine/overworld/wildmons.asm

@@ -313,14 +313,14 @@ ChooseWildEncounter:
 	inc b
 ; Store the level
 .ok
+; BUG: ChooseWildEncounter doesn't really validate the wild Pokemon species (see docs/bugs_and_glitches.md)
 	ld a, b
 	ld [wCurPartyLevel], a
 	ld b, [hl]
-	; ld a, b
 	call ValidateTempWildMonSpecies
 	jr c, .nowildbattle
 
-	ld a, b ; This is in the wrong place.
+	ld a, b
 	cp UNOWN
 	jr nz, .done