Add some comments

src/play_controller.hpp

@@ -427,6 +427,12 @@ private:
 
 protected:
 	mutable bool ignore_replay_errors_;
+	/// true when the controller of the currently playing side has changed.
+	/// this can mean for example:
+	/// - The currently active side was reassigned from/to another player in a mp game
+	/// - The replay controller was disabled ('continue play' button)
+	/// - The currently active side was droided / undroided.
+	/// - A side was set to idle.
 	bool player_type_changed_;
 	virtual void sync_end_turn() {}
 	virtual void check_time_over();

src/playsingle_controller.cpp

@@ -747,6 +747,8 @@ bool playsingle_controller::should_return_to_play_side() const
 void playsingle_controller::on_replay_end(bool is_unit_test)
 {
 	if(is_networked_mp()) {
+		// we are using the "Back to turn (replay)" feature
+		// And have reached the current gamestate: end the replay and continue normally.
 		set_player_type_changed();
 	} else if(is_unit_test) {
 		replay_controller_->return_to_play_side();

src/playsingle_controller.hpp

@@ -79,8 +79,12 @@ protected:
 	const cursor::setter cursor_setter_;
 	gui::floating_textbox textbox_info_;
 
+	/// Helper to send our actions to the server
+	/// Used by turn_data_
 	replay_network_sender replay_sender_;
+	/// Used by turn_data_
 	playturn_network_adapter network_reader_;
+	/// Helper to read and execute (in particular replay data/ user actions ) messsages from the server
 	turn_info turn_data_;
 	enum END_TURN_STATE
 	{
@@ -91,8 +95,13 @@ protected:
 		/** An [end_turn] was added to the replay. */
 		END_TURN_SYNCED,
 	};
+
 	END_TURN_STATE end_turn_;
-	bool skip_next_turn_, ai_fallback_;
+	bool skip_next_turn_;
+	/// true when the current side is actually an ai side but was taken over by a human (usually for debugging purposes),
+	/// we need this variable to remember to give the ai control back next turn.
+	bool ai_fallback_;
+	/// non-null when replay mode in active, is used in singleplayer and for the "back to turn" feature in multiplayer.
 	std::unique_ptr<replay_controller> replay_controller_;
 	void linger();
 	void sync_end_turn() override;

src/replay_controller.hpp

@@ -86,7 +86,11 @@ private:
 		SHOW_ALL,
 	};
 	std::optional<REPLAY_VISION> vision_;
+	/// When the "Reset" button is pressed reset the gamestate to this
+	/// serialized gamestaten, the initial gamestate.
 	std::shared_ptr<config> reset_state_;
+	/// Called when there are no more moves in the [replay] to process
 	std::function<void()> on_end_replay_;
+	/// Used by unit tests.
 	bool return_to_play_side_;
 };