leave some documentation on Zone classes

cockatrice/src/game/board/abstract_graphics_item.h

@@ -13,6 +13,9 @@ enum GraphicsItemType
     typeOther = QGraphicsItem::UserType + 6
 };
 
+/**
+ * Parent class of all objects that appear in a game.
+ */
 class AbstractGraphicsItem : public QObject, public QGraphicsItem
 {
     Q_OBJECT

cockatrice/src/game/player/player.h

@@ -68,6 +68,9 @@ class ZoneViewZone;
 
 const int MAX_TOKENS_PER_DIALOG = 99;
 
+/**
+ * The entire graphical area belonging to a single player.
+ */
 class PlayerArea : public QObject, public QGraphicsItem
 {
     Q_OBJECT

cockatrice/src/game/zones/card_zone.cpp

@@ -11,6 +11,14 @@
 #include <QGraphicsSceneMouseEvent>
 #include <QMenu>
 
+/**
+ * @param _p the player that the zone belongs to
+ * @param _name internal name of the zone
+ * @param _isShufflable whether it makes sense to shuffle this zone by default after viewing it
+ * @param _contentsKnown whether the cards in the zone are known to the client
+ * @param parent the parent graphics object.
+ * @param _isView whether this zone is a view of another zone. Modifications to a view should modify the original
+ */
 CardZone::CardZone(Player *_p,
                    const QString &_name,
                    bool _hasCardAttr,

cockatrice/src/game/zones/card_zone.h

@@ -14,6 +14,12 @@ class QAction;
 class QPainter;
 class CardDragItem;
 
+/**
+ * A zone in the game that can contain cards.
+ * This class contains methods to get and modify the cards that are contained inside this zone.
+ *
+ * The cards are stored as a list of `CardItem*`.
+ */
 class CardZone : public AbstractGraphicsItem
 {
     Q_OBJECT

cockatrice/src/game/zones/pile_zone.h

@@ -3,6 +3,10 @@
 
 #include "card_zone.h"
 
+/**
+ * A CardZone where the cards are in a single pile instead of being laid out.
+ * Usually only top card is accessible by clicking.
+ */
 class PileZone : public CardZone
 {
     Q_OBJECT

cockatrice/src/game/zones/select_zone.h

@@ -3,6 +3,9 @@
 
 #include "card_zone.h"
 
+/**
+ * A CardZone where the cards are laid out, with each card directly interactable by clicking.
+ */
 class SelectZone : public CardZone
 {
     Q_OBJECT

cockatrice/src/game/zones/view_zone.cpp

@@ -16,6 +16,13 @@
 #include <QPainter>
 #include <QtMath>
 
+/**
+ * @param _p the player that the cards are revealed to.
+ * @param _origZone the zone the cards were revealed from.
+ * @param _revealZone if false, the cards will be face down.
+ * @param _writeableRevealZone whether the player can interact with the revealed cards.
+ * @param parent the parent QGraphicsWidget containing the reveal zone
+ */
 ZoneViewZone::ZoneViewZone(Player *_p,
                            CardZone *_origZone,
                            int _numberCards,

cockatrice/src/game/zones/view_zone.h

@@ -10,6 +10,15 @@ class Response;
 class ServerInfo_Card;
 class QGraphicsSceneWheelEvent;
 
+/**
+ * A CardZone that is a view into another CardZone.
+ * If this zone is writable, then modifications to this zone will be reflected in the underlying zone.
+ *
+ * Most interactions with StackZones are handled through a zone view.
+ * For example, viewing the deck/graveyard/exile is handled through a view.
+ *
+ * Handles both limited reveals (eg. look at top X cards) and full zone reveals (eg. searching the deck).
+ */
 class ZoneViewZone : public SelectZone, public QGraphicsLayoutItem
 {
     Q_OBJECT

cockatrice/src/game/zones/view_zone_widget.cpp

@@ -17,6 +17,13 @@
 #include <QStyleOption>
 #include <QStyleOptionTitleBar>
 
+/**
+ * @param _player the player the cards were revealed to.
+ * @param _origZone the zone the cards were revealed from.
+ * @param numberCards num of cards to reveal from the zone. Ex: scry the top 3 cards. Use -1 to reveal the entire zone.
+ * @param _revealZone if false, the cards will be face down.
+ * @param _writeableRevealZone whether the player can interact with the revealed cards.
+ */
 ZoneViewWidget::ZoneViewWidget(Player *_player,
                                CardZone *_origZone,
                                int numberCards,

cockatrice/src/game/zones/view_zone_widget.h

@@ -31,6 +31,12 @@ public slots:
     }
 };
 
+/**
+ * A QGraphicsWidget that holds a ZoneViewZone.
+ *
+ * Some zone views allow sorting.
+ * This widget will display the sort options when relevant, and forward the values of the options to the ZoneViewZone.
+ */
 class ZoneViewWidget : public QGraphicsWidget
 {
     Q_OBJECT