Add a few more comments

README.md

@@ -5,6 +5,10 @@ Allows a bot to switch places with a player on the opposite team if teams are ba
 Attempts to be a relatively clean fix to freely change teams instead of switching to Spectator
 and then joining the other team.
 
+This is done by replicating a fake `mp_teams_unbalance_limit` value to clients that can switch
+to a team with at least one bot player so they can open the menu and switch normally.  The
+`jointeam` command is also hooked, forcing a bot to swap at the same time.
+
 ## A "CSRD Internal" Plugin
 
 This is a plugin mainly intended for use in [Pikachu's Canadian Server of Romance and

scripting/csrd_bot_swap.sp

@@ -56,6 +56,9 @@ public void OnTeamStateChange(Event event, const char[] name, bool dontBroadcast
 
 /**
  * Called when the number of players on a team change.
+ * 
+ * Updates the `mp_teams_unbalance_limit` value tramsmitted to clients, so they can use the team
+ * switch UI and freely switch to the other team if a bot is available for swapping.
  */
 public void OnTeamStateChangePost(any data) {
 	ConVar unbalanceLimit = FindConVar("mp_teams_unbalance_limit");
@@ -100,6 +103,18 @@ public void OnTeamStateChangePost(any data) {
 	}
 }
 
+/**
+ * Called when a player has requested to switch teams, before the game's logic happens.
+ * 
+ * If the player is on a playing team and wants to switch to the other one, moves a bot from
+ * their desired team to their current one.  The game then processes the team change command and
+ * moves them to their desired team.
+ * 
+ * This won't quite work the way it should if some other plugin blocks the team change further
+ * down in their event hook.  A detour on CTFPlayer::HandleCommand_JoinTeam() would do its work
+ * after most plugins process the command, but this hasn't been an issue on my setup.
+ * 
+ */
 public Action OnTeamChangeRequested(int client, const char[] name, int argc) {
 	if (TF2_GetTeamClientCount(TFTeam_Red) == TF2_GetTeamClientCount(TFTeam_Blue)) {
 		TFTeam team = TF2_GetClientTeam(client);
@@ -122,7 +137,7 @@ public Action OnTeamChangeRequested(int client, const char[] name, int argc) {
 }
 
 /**
- * Moves a bot from one playing team to the other.
+ * Moves a random bot from one playing team to the other.
  */
 void SwapFakeClient(TFTeam sourceTeam) {
 	if (sourceTeam != TFTeam_Red && sourceTeam != TFTeam_Blue) {