Add comments to display and display_context, silence 64-to-32 warnings

The static casts are for -Wshorten-64-to-32 warnings, it would take a
lot of work to fix this in a better way.

src/display.hpp

@@ -80,6 +80,9 @@ namespace wb {
 
 class gamemap;
 
+/**
+ * Sort-of-Singleton that many classes, both GUI and non-GUI, use to access the game data.
+ */
 class display : public gui2::top_level_drawable
 {
 public:
@@ -108,9 +111,23 @@ class display : public gui2::top_level_drawable
 
 	bool team_valid() const;
 
-	/** The viewing team is the team currently viewing the game. */
+	/**
+	 * The viewing team is the team currently viewing the game. It's the team whose gold and income
+	 * is shown in the top bar of the default theme.
+	 *
+	 * For players, it will be their side (or one of them, if they control multiple sides).
+	 *
+	 * The value returned is a 0-based index into the vector returned by get_teams().
+	 */
 	std::size_t viewing_team() const { return currentTeam_; }
-	int viewing_side() const { return currentTeam_ + 1; }
+	/**
+	 * The 1-based equivalent of the 0-based viewing_team() function. This is the side-number that
+	 * WML uses.
+	 *
+	 * TODO: provide a better interface in a better place (consistent base numbers, and not in a GUI
+	 * class).
+	 */
+	int viewing_side() const { return static_cast<int>(currentTeam_ + 1); }
 
 	/**
 	 * Sets the team controlled by the player using the computer.

src/display_context.hpp

@@ -13,13 +13,6 @@
 	See the COPYING file for more details.
 */
 
-/**
- *
- * This class is an abstract base class designed to simplify the use
- * of the display object.
- *
- **/
-
 #pragma once
 
 #include "units/orb_status.hpp"
@@ -34,6 +27,10 @@ class unit_map;
 class unit;
 struct map_location;
 
+/**
+ * Abstract class for exposing game data that doesn't depend on the GUI, however which for historical
+ * reasons is generally accessed via the GUI method display::get_singleton().
+ */
 class display_context
 {
 public:
@@ -42,6 +39,8 @@ class display_context
 	virtual const unit_map & units() const = 0;
 	virtual const std::vector<std::string> & hidden_label_categories() const = 0;
 	virtual std::vector<std::string> & hidden_label_categories() = 0;
+
+	/** This getter takes a 1-based side number, not a 0-based team number. */
 	const team& get_team(int side) const;
 
 	// this one is only a template function to prevent compilation erros when class team is an incomplete type.

src/game_display.hpp

@@ -198,7 +198,7 @@ class game_display : public display
 	static void clear_debug_highlights() { debugHighlights_.clear(); }
 
 	/** The playing team is the team whose turn it is. */
-	virtual int playing_side() const override { return activeTeam_ + 1; }
+	virtual int playing_side() const override { return static_cast<int>(activeTeam_) + 1; }
 
 	std::string current_team_name() const;