Added comments to royaleast.py and sanibel.py (#404)

* Added comments to royaleast.py and sanibel.py

* Update royaleast.py

I have removed unnecessary white spaces and edited the longer lines.

* Update sanibel.py

I have removed the white spaces and edited the longer lines.

* Update royaleast.py

* Update sanibel.py

---------

Co-authored-by: Surani02 <surainaranpanawa@gmail.com>

pysollib/games/royaleast.py

@@ -21,92 +21,126 @@
 #
 # ---------------------------------------------------------------------------##
 
+# Importing necessary modules from the pysollib library for the game
 from pysollib.game import Game
 from pysollib.gamedb import GI, GameInfo, registerGame
 from pysollib.hint import CautiousDefaultHint
 from pysollib.layout import Layout
-from pysollib.stack import \
-        RK_RowStack, \
-        SS_FoundationStack, \
-        WasteStack, \
-        WasteTalonStack
+from pysollib.stack import (
+    RK_RowStack,  # Row stack for holding cards
+    SS_FoundationStack,  # Foundation stack where cards are placed to win
+    WasteStack,  # Waste stack for discarded cards
+    WasteTalonStack  # Talon stack for dealing cards
+)
 
 # ************************************************************************
 # * Royal East
 # ************************************************************************
 
 
 class RoyalEast(Game):
-    Hint_Class = CautiousDefaultHint
+    """
+    Class representing the Royal East card game.
+    It defines the layout, rules, and mechanics of the game.
+    """
+
+    Hint_Class = CautiousDefaultHint  # Setting the hint class for this game
 
     #
     # game layout
     #
 
     def createGame(self):
-        # create layout
+        """Set up the game layout and initialize the stacks."""
+        # Initialize the layout and stack container
         l, s = Layout(self), self.s
 
-        # set window
-        self.setSize(l.XM + 5.5*l.XS, l.YM + 4*l.YS)
+        # Set the game window size
+        self.setSize(l.XM + 5.5 * l.XS, l.YM + 4 * l.YS)
 
-        # extra settings
+        # Initialize base card variable
         self.base_card = None
 
-        # create stacks
+        # Create foundation stacks (where cards are stacked by suit)
         for i in range(4):
             dx, dy = ((0, 0), (2, 0), (0, 2), (2, 2))[i]
-            x, y = l.XM + (2*dx+5)*l.XS//2, l.YM + (2*dy+1)*l.YS//2
+            x, y = (
+                l.XM + (2 * dx + 5) * l.XS // 2,
+                l.YM + (2 * dy + 1) * l.YS // 2
+            )
             stack = SS_FoundationStack(x, y, self, i, mod=13, max_move=0)
-            stack.CARD_YOFFSET = 0
+            stack.CARD_YOFFSET = 0  # No vertical card offset
             s.foundations.append(stack)
+
+        # Create row stacks (where cards are initially dealt)
         for i in range(5):
             dx, dy = ((1, 0), (0, 1), (1, 1), (2, 1), (1, 2))[i]
-            x, y = l.XM + (2*dx+5)*l.XS//2, l.YM + (2*dy+1)*l.YS//2
+            x, y = (
+                l.XM + (2 * dx + 5) * l.XS // 2,
+                l.YM + (2 * dy + 1) * l.YS // 2
+            )
             stack = RK_RowStack(x, y, self, mod=13, max_move=1)
-            stack.CARD_YOFFSET = 0
+            stack.CARD_YOFFSET = 0  # No vertical card offset
             s.rows.append(stack)
-        x, y = l.XM, l.YM + 3*l.YS//2
-        s.talon = WasteTalonStack(x, y, self, max_rounds=1)
-        l.createText(s.talon, "s")
+
+        # Create the talon (where undealt cards are stored) and waste stacks
+        x, y = l.XM, l.YM + 3 * l.YS // 2
+        s.talon = WasteTalonStack(
+            x, y, self, max_rounds=1
+        )  # Talon with one round of cards
+        l.createText(s.talon, "s")  # Label for the talon
         x = x + l.XS
-        s.waste = WasteStack(x, y, self)
-        l.createText(s.waste, "s")
+        s.waste = WasteStack(x, y, self)  # Waste stack for discarded cards
+        l.createText(s.waste, "s")  # Label for the waste
 
-        # define stack-groups
+        # Define stack groups (standard Solitaire layout grouping)
         l.defaultStackGroups()
 
     #
     # game overrides
     #
 
     def startGame(self):
+        """Start a new game by setting up the base card and dealing cards."""
+        # Set the base card as the last card in the talon stack
         self.base_card = self.s.talon.cards[-1]
+
+        # Set the base rank for each foundation stack based on the base card
         for s in self.s.foundations:
             s.cap.base_rank = self.base_card.rank
-        # deal base card to Foundations
+
+        # Deal the base card to the corresponding foundation stack
         c = self.s.talon.getCard()
         to_stack = self.s.foundations[c.suit * self.gameinfo.decks]
         self.flipMove(self.s.talon)
         self.moveMove(1, self.s.talon, to_stack, frames=0)
-        # deal rows
+
+        # Deal cards to row stacks
         self._startAndDealRowAndCards()
 
     def _restoreGameHook(self, game):
+        """Restore the game from a saved state."""
+        # Restore the base card based on its saved ID
         self.base_card = self.cards[game.loadinfo.base_card_id]
+
+        # Set the base rank for the foundation stacks
         for s in self.s.foundations:
             s.cap.base_rank = self.base_card.rank
 
     def _loadGameHook(self, p):
-        self.loadinfo.addattr(base_card_id=None)    # register extra load var.
+        """Load additional game state during game restoration."""
+        # Register an additional variable to save the base card's ID
+        self.loadinfo.addattr(base_card_id=None)
         self.loadinfo.base_card_id = p.load()
 
     def _saveGameHook(self, p):
+        """Save the game state including the base card's ID."""
         p.dump(self.base_card.id)
 
+    # Define matching highlights for the game
     shallHighlightMatch = Game._shallHighlightMatch_RKW
 
 
-# register the game
+# Register the Royal East game in the game database
 registerGame(GameInfo(93, RoyalEast, "Royal East",
                       GI.GT_1DECK_TYPE, 1, 0, GI.SL_BALANCED))

pysollib/games/sanibel.py

@@ -21,15 +21,17 @@
 #
 # ---------------------------------------------------------------------------##
 
+# Importing necessary modules for the Sanibel card game
 from pysollib.gamedb import GI, GameInfo, registerGame
-from pysollib.games.gypsy import Gypsy
-from pysollib.hint import Yukon_Hint
-from pysollib.layout import Layout
-from pysollib.stack import \
-        SS_FoundationStack, \
-        StackWrapper, \
-        WasteTalonStack, \
-        Yukon_AC_RowStack
+from pysollib.games.gypsy import Gypsy  # Import Gypsy, base class for Sanibel
+from pysollib.hint import Yukon_Hint  # Hint mechanism for Yukon-based games
+from pysollib.layout import Layout  # Layout configuration for the game
+from pysollib.stack import (
+    SS_FoundationStack,  # Foundation stack for completed suits
+    StackWrapper,  # Wrapper for stack with additional functionality
+    WasteTalonStack,  # Talon stack for dealing cards
+    Yukon_AC_RowStack  # Row stack class used in Yukon-like games
+)
 
 # ************************************************************************
 # * Sanibel
@@ -38,26 +40,52 @@
 
 
 class Sanibel(Gypsy):
-    Layout_Method = staticmethod(Layout.klondikeLayout)
-    Talon_Class = StackWrapper(WasteTalonStack, max_rounds=1)
-    Foundation_Class = StackWrapper(SS_FoundationStack, max_move=0)
-    RowStack_Class = Yukon_AC_RowStack
-    Hint_Class = Yukon_Hint
+    """
+    Class representing the Sanibel card game, a variant of Yukon.
+    It uses a similar layout and gameplay mechanics to Yukon but with
+    specific rules defined in the class.
+    """
+
+    Layout_Method = staticmethod(Layout.klondikeLayout)  # Use Klondike layout
+    Talon_Class = StackWrapper(
+        WasteTalonStack, max_rounds=1
+    )  # One round Talon
+    Foundation_Class = StackWrapper(
+        SS_FoundationStack, max_move=0
+    )  # Foundation stacks
+    RowStack_Class = Yukon_AC_RowStack  # Row stack for Yukon gameplay
+    Hint_Class = Yukon_Hint  # Hint system for Yukon-style games
 
     def createGame(self):
+        """
+        Set up the game with a specific number of rows, waste piles,
+        and initial playcards.
+        """
+        # Create a Gypsy-like game with 10 rows, 1 waste stack,
+        # and 23 playcards
         Gypsy.createGame(self, rows=10, waste=1, playcards=23)
 
     def startGame(self):
+        """
+        Start the game by dealing cards into the talon and rows.
+        """
+        # Deal the first three rows from the talon
         for i in range(3):
             self.s.talon.dealRow(flip=0, frames=0)
+        # Deal 6 more rows
         self._startDealNumRows(6)
+        # Deal the last row and cards from the talon
         self.s.talon.dealRow()
-        self.s.talon.dealCards()          # deal first card to WasteStack
+        self.s.talon.dealCards()  # Deal the first card to the WasteStack
 
     def getHighlightPilesStacks(self):
+        """
+        Returns an empty tuple, meaning no specific stacks will be highlighted.
+        """
         return ()
 
 
+# Register the Sanibel game in the game database with its associated info
 registerGame(GameInfo(201, Sanibel, "Sanibel",
                       GI.GT_YUKON | GI.GT_CONTRIB | GI.GT_ORIGINAL, 2, 0,
                       GI.SL_MOSTLY_SKILL))