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

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

engine/battle/move_effects/beat_up.asm

@@ -24,6 +24,7 @@ BattleCommand_BeatUp:
 	ld [wCurBeatUpPartyMon], a
 
 .got_mon
+; BUG: Beat Up can desynchronize link battles (see docs/bugs_and_glitches.md)
 	ld a, [wCurBeatUpPartyMon]
 	ld hl, wPartyMonNicknames
 	call GetNickname
@@ -35,8 +36,6 @@ BattleCommand_BeatUp:
 	ld a, [wCurBeatUpPartyMon]
 	ld c, a
 	ld a, [wCurBattleMon]
-	; BUG: this can desynchronize link battles
-	; Change "cp [hl]" to "cp c" to fix
 	cp [hl]
 	ld hl, wBattleMonStatus
 	jr z, .active_mon
@@ -196,6 +195,7 @@ BattleCommand_BeatUp:
 	jp SkipToBattleCommand
 
 BattleCommand_BeatUpFailText:
+; BUG: Beat Up may trigger King's Rock even if it failed (see docs/bugs_and_glitches.md)
 	ld a, [wBeatUpHitAtLeastOnce]
 	and a
 	ret nz

engine/battle/move_effects/belly_drum.asm

@@ -1,7 +1,5 @@
 BattleCommand_BellyDrum:
-; This command is buggy because it raises the user's attack
-; before checking that it has enough HP to use the move.
-; Swap the order of these two blocks to fix.
+; BUG: Belly Drum sharply boosts Attack even with under 50% HP (see docs/bugs_and_glitches.md)
 	call BattleCommand_AttackUp2
 	ld a, [wAttackMissed]
 	and a

engine/battle/move_effects/counter.asm

@@ -34,7 +34,7 @@ BattleCommand_Counter:
 	cp SPECIAL
 	ret nc
 
-	; BUG: Move should fail with all non-damaging battle actions
+; BUG: Counter and Mirror Coat still work if the opponent uses an item (see docs/bugs_and_glitches.md)
 	ld hl, wCurDamage
 	ld a, [hli]
 	or [hl]

engine/battle/move_effects/frustration.asm

@@ -1,4 +1,5 @@
 BattleCommand_FrustrationPower:
+; BUG: Return and Frustration deal no damage when the user's happiness is low or high, respectively (see docs/bugs_and_glitches.md)
 	push bc
 	ld hl, wBattleMonHappiness
 	ldh a, [hBattleTurn]

engine/battle/move_effects/mirror_coat.asm

@@ -35,7 +35,7 @@ BattleCommand_MirrorCoat:
 	cp SPECIAL
 	ret c
 
-	; BUG: Move should fail with all non-damaging battle actions
+; BUG: Counter and Mirror Coat still work if the opponent uses an item (see docs/bugs_and_glitches.md)
 	ld hl, wCurDamage
 	ld a, [hli]
 	or [hl]

engine/battle/move_effects/present.asm

@@ -1,4 +1,5 @@
 BattleCommand_Present:
+; BUG: Present damage is incorrect in link battles (see docs/bugs_and_glitches.md)
 	ld a, [wLinkMode]
 	cp LINK_COLOSSEUM
 	jr z, .colosseum_skippush

engine/battle/move_effects/return.asm

@@ -1,4 +1,5 @@
 BattleCommand_HappinessPower:
+; BUG: Return and Frustration deal no damage when the user's happiness is low or high, respectively (see docs/bugs_and_glitches.md)
 	push bc
 	ld hl, wBattleMonHappiness
 	ldh a, [hBattleTurn]

engine/battle/move_effects/sketch.asm

@@ -12,6 +12,7 @@ BattleCommand_Sketch:
 	call CheckSubstituteOpp
 	jp nz, .fail
 ; If the opponent is transformed, fail.
+; BUG: A Transformed Pokémon can use Sketch and learn otherwise unobtainable moves (see docs/bugs_and_glitches.md)
 	ld a, BATTLE_VARS_SUBSTATUS5_OPP
 	call GetBattleVarAddr
 	bit SUBSTATUS_TRANSFORMED, [hl]

engine/battle/move_effects/teleport.asm

@@ -66,14 +66,13 @@ BattleCommand_Teleport:
 	inc c
 	; Generate a number less than c
 .loop_enemy
+; BUG: Wild Pokémon can always Teleport regardless of level difference (see docs/bugs_and_glitches.md)
 	call BattleRandom
 	cp c
 	jr nc, .loop_enemy
 	; b = player level / 4
 	srl b
 	srl b
-	; This should be "jr c, .failed"
-	; As written, it makes enemy use of Teleport always succeed if able
 	cp b
 	jr nc, .run_away