Rename Game.comment to Game.description (#755)

edwardchalstrey1 · web-flow · commit 3c052b19e5e4 · 2026-02-09T11:48:07.000Z
diff --git a/ChangeLog b/ChangeLog
@@ -1,5 +1,11 @@
 # Changelog
 
+## [16.6.0] - unreleased
+
+### Changed
+- `Game.comment` has been renamed to `Game.description`
+
+
 ## [16.5.1] - unreleased
 
 ### Fixed
diff --git a/doc/pygambit.api.rst b/doc/pygambit.api.rst
@@ -95,7 +95,7 @@ Information about the game
    :toctree: api/
 
    Game.title
-   Game.comment
+   Game.description
    Game.is_const_sum
    Game.is_tree
    Game.is_perfect_recall
diff --git a/src/games/file.cc b/src/games/file.cc
@@ -440,7 +440,7 @@ Game BuildNfg(GameFileLexer &p_parser, TableFileGame &p_data)
   // If this looks lke an outcome-based format, then don't create outcomes in advance
   Game nfg = NewTable(p_data.NumStrategies(), p_parser.GetCurrentToken() == TOKEN_LBRACE);
   nfg->SetTitle(p_data.m_title);
-  nfg->SetComment(p_data.m_comment);
+  nfg->SetDescription(p_data.m_comment);
 
   for (auto player : nfg->GetPlayers()) {
     player->SetLabel(p_data.GetPlayer(player->GetNumber()));
@@ -865,7 +865,7 @@ Game ReadEfgFile(std::istream &p_stream, bool p_normalizeLabels /* = false */)
   ReadPlayers(parser, game, treeData);
   if (parser.GetNextToken() == TOKEN_TEXT) {
     // Read optional comment
-    game->SetComment(parser.GetLastText());
+    game->SetDescription(parser.GetLastText());
     parser.GetNextToken();
   }
   ParseNode(parser, game, game->GetRoot(), treeData);
diff --git a/src/games/game.cc b/src/games/game.cc
@@ -229,7 +229,7 @@ void GameRep::WriteNfgFile(std::ostream &p_file) const
     }) << std::endl;
   }
   p_file << "}" << std::endl;
-  p_file << std::quoted(GetComment()) << std::endl << std::endl;
+  p_file << std::quoted(GetDescription()) << std::endl << std::endl;
 
   for (auto iter : StrategyContingencies(
            StrategySupportProfile(std::const_pointer_cast<GameRep>(shared_from_this())))) {
diff --git a/src/games/game.h b/src/games/game.h
@@ -888,9 +888,9 @@ class GameRep : public std::enable_shared_from_this<GameRep> {
   virtual void SetTitle(const std::string &p_title) { m_title = p_title; }
 
   /// Get the text comment associated with the game
-  virtual const std::string &GetComment() const { return m_comment; }
+  virtual const std::string &GetDescription() const { return m_comment; }
   /// Set the text comment associated with the game
-  virtual void SetComment(const std::string &p_comment) { m_comment = p_comment; }
+  virtual void SetDescription(const std::string &p_comment) { m_comment = p_comment; }
 
   /// Return the version number of the game.  The version is incremented after each
   /// substantive change to the game (i.e. not merely involving labels)
diff --git a/src/games/gametable.cc b/src/games/gametable.cc
@@ -469,7 +469,7 @@ void GameTableRep::WriteNfgFile(std::ostream &p_file) const
     }) << std::endl;
   }
   p_file << "}" << std::endl;
-  p_file << std::quoted(GetComment()) << std::endl << std::endl;
+  p_file << std::quoted(GetDescription()) << std::endl << std::endl;
 
   p_file << "{" << std::endl;
   for (auto outcome : m_outcomes) {
diff --git a/src/games/gametree.cc b/src/games/gametree.cc
@@ -1196,7 +1196,7 @@ void GameTreeRep::WriteEfgFile(std::ostream &p_file, const GameNode &p_subtree /
          << FormatList(GetPlayers(),
                        [](const GamePlayer &p) { return QuoteString(p->GetLabel()); })
          << std::endl;
-  p_file << std::quoted(GetComment()) << std::endl << std::endl;
+  p_file << std::quoted(GetDescription()) << std::endl << std::endl;
   Gambit::WriteEfgFile(p_file, (p_subtree) ? p_subtree : GetRoot());
 }
 
diff --git a/src/games/stratspt.cc b/src/games/stratspt.cc
@@ -100,7 +100,7 @@ void StrategySupportProfile::WriteNfgFile(std::ostream &p_file) const
     }) << std::endl;
   }
   p_file << "}" << std::endl;
-  p_file << std::quoted(m_game->GetComment()) << std::endl << std::endl;
+  p_file << std::quoted(m_game->GetDescription()) << std::endl << std::endl;
 
   for (const auto &iter : StrategyContingencies(*this)) {
     p_file << FormatList(
diff --git a/src/gui/dlgameprop.cc b/src/gui/dlgameprop.cc
@@ -51,7 +51,7 @@ GamePropertiesDialog::GamePropertiesDialog(wxWindow *p_parent, GameDocument *p_d
   commentSizer->Add(new wxStaticText(this, wxID_STATIC, _("Comment")), 0, wxALL | wxALIGN_CENTER,
                     5);
   m_comment = new wxTextCtrl(this, wxID_ANY,
-                             wxString(m_doc->GetGame()->GetComment().c_str(), *wxConvCurrent),
+                             wxString(m_doc->GetGame()->GetDescription().c_str(), *wxConvCurrent),
                              wxDefaultPosition, wxSize(400, -1), wxTE_MULTILINE);
   commentSizer->Add(m_comment, 1, wxALL | wxALIGN_CENTER, 5);
   topSizer->Add(commentSizer, 1, wxALL | wxEXPAND, 0);
diff --git a/src/gui/dlgameprop.h b/src/gui/dlgameprop.h
@@ -34,7 +34,7 @@ class GamePropertiesDialog final : public wxDialog {
 
   // Data access (only valid when ShowModal() returns with wxID_OK)
   wxString GetTitle() const override { return m_title->GetValue(); }
-  wxString GetComment() const { return m_comment->GetValue(); }
+  wxString GetDescription() const { return m_comment->GetValue(); }
 };
 
 } // namespace Gambit::GUI
diff --git a/src/gui/gamedoc.cc b/src/gui/gamedoc.cc
@@ -406,7 +406,7 @@ void GameDocument::DoExportNfg(const wxString &p_filename)
 void GameDocument::DoSetTitle(const wxString &p_title, const wxString &p_comment)
 {
   m_game->SetTitle(static_cast<const char *>(p_title.mb_str()));
-  m_game->SetComment(static_cast<const char *>(p_comment.mb_str()));
+  m_game->SetDescription(static_cast<const char *>(p_comment.mb_str()));
   UpdateViews(GBT_DOC_MODIFIED_LABELS);
 }
 
diff --git a/src/gui/gameframe.cc b/src/gui/gameframe.cc
@@ -1058,7 +1058,7 @@ void GameFrame::OnEditGame(wxCommandEvent &)
 {
   GamePropertiesDialog dialog(this, m_doc);
   if (dialog.ShowModal() == wxID_OK) {
-    m_doc->DoSetTitle(dialog.GetTitle(), dialog.GetComment());
+    m_doc->DoSetTitle(dialog.GetTitle(), dialog.GetDescription());
   }
 }
 
diff --git a/src/pygambit/gambit.pxd b/src/pygambit/gambit.pxd
@@ -253,8 +253,8 @@ cdef extern from "games/game.h":
         string GetTitle() except +
         void SetTitle(string) except +
 
-        string GetComment() except +
-        void SetComment(string) except +
+        string GetDescription() except +
+        void SetDescription(string) except +
 
         int NumPlayers() except +
         c_GamePlayer GetPlayer(int) except +IndexError
diff --git a/src/pygambit/game.pxi b/src/pygambit/game.pxi
@@ -661,17 +661,20 @@ class Game:
         self.game.deref().SetTitle(value.encode("ascii"))
 
     @property
-    def comment(self) -> str:
-        """Get or set the comment of the game.
+    def description(self) -> str:
+        """Get or set the description of the game.
 
-        A game's comment is an arbitrary string, and may be more discursive
+        A game's description is an arbitrary string, and may be more discursive
         than a title.
+
+        .. versionchanged:: 16.6.0
+           Renamed ``Game.comment`` to ``Game.description``.
         """
-        return self.game.deref().GetComment().decode("ascii")
+        return self.game.deref().GetDescription().decode("ascii")
 
-    @comment.setter
-    def comment(self, value: str) -> None:
-        self.game.deref().SetComment(value.encode("ascii"))
+    @description.setter
+    def description(self, value: str) -> None:
+        self.game.deref().SetDescription(value.encode("ascii"))
 
     @property
     def actions(self) -> GameActions:
diff --git a/tests/test_extensive.py b/tests/test_extensive.py
@@ -25,12 +25,12 @@ def test_game_title(title: str):
 
 
 @pytest.mark.parametrize(
-    "comment", ["This is a comment describing the game in more detail"]
+    "description", ["This describes the game in more detail than the title"]
 )
-def test_game_comment(comment: str):
+def test_game_description(description: str):
     game = gbt.Game.new_tree()
-    game.comment = comment
-    assert game.comment == comment
+    game.description = description
+    assert game.description == description
 
 
 @pytest.mark.parametrize("players", [["Alice"], ["Oscar", "Felix"]])

Original file line number	Diff line number	Diff line change
`@@ -229,7 +229,7 @@ void GameRep::WriteNfgFile(std::ostream &p_file) const`
`229`	`229`	`}) << std::endl;`
`230`	`230`	`}`
`231`	`231`	`p_file << "}" << std::endl;`
`232`		`- p_file << std::quoted(GetComment()) << std::endl << std::endl;`
	`232`	`+ p_file << std::quoted(GetDescription()) << std::endl << std::endl;`
`233`	`233`
`234`	`234`	`for (auto iter : StrategyContingencies(`
`235`	`235`	`StrategySupportProfile(std::const_pointer_cast<GameRep>(shared_from_this())))) {`
Original file line number	Diff line number	Diff line change
`@@ -469,7 +469,7 @@ void GameTableRep::WriteNfgFile(std::ostream &p_file) const`
`469`	`469`	`}) << std::endl;`
`470`	`470`	`}`
`471`	`471`	`p_file << "}" << std::endl;`
`472`		`- p_file << std::quoted(GetComment()) << std::endl << std::endl;`
	`472`	`+ p_file << std::quoted(GetDescription()) << std::endl << std::endl;`
`473`	`473`
`474`	`474`	`p_file << "{" << std::endl;`
`475`	`475`	`for (auto outcome : m_outcomes) {`
Original file line number	Diff line number	Diff line change
`@@ -1196,7 +1196,7 @@ void GameTreeRep::WriteEfgFile(std::ostream &p_file, const GameNode &p_subtree /`
`1196`	`1196`	`<< FormatList(GetPlayers(),`
`1197`	`1197`	`[](const GamePlayer &p) { return QuoteString(p->GetLabel()); })`
`1198`	`1198`	`<< std::endl;`
`1199`		`- p_file << std::quoted(GetComment()) << std::endl << std::endl;`
	`1199`	`+ p_file << std::quoted(GetDescription()) << std::endl << std::endl;`
`1200`	`1200`	`Gambit::WriteEfgFile(p_file, (p_subtree) ? p_subtree : GetRoot());`
`1201`	`1201`	`}`
`1202`	`1202`
Original file line number	Diff line number	Diff line change
`@@ -100,7 +100,7 @@ void StrategySupportProfile::WriteNfgFile(std::ostream &p_file) const`
`100`	`100`	`}) << std::endl;`
`101`	`101`	`}`
`102`	`102`	`p_file << "}" << std::endl;`
`103`		`- p_file << std::quoted(m_game->GetComment()) << std::endl << std::endl;`
	`103`	`+ p_file << std::quoted(m_game->GetDescription()) << std::endl << std::endl;`
`104`	`104`
`105`	`105`	`for (const auto &iter : StrategyContingencies(*this)) {`
`106`	`106`	`p_file << FormatList(`