leave some documentation on Zone classes (#5199)

* leave some documentation on Zone classes

* small refactor

* undo functional change from refactor and clean up comments

* move variables into if block

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,15 @@
 #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.
+ * Pass in a negative number to reveal the entire zone.
+ * -1 specifically will give the option to shuffle the zone upon closing the window.
+ * @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,
@@ -31,10 +40,10 @@ ZoneViewWidget::ZoneViewWidget(Player *_player,
     setFlag(ItemIgnoresTransformations);
 
     QGraphicsLinearLayout *vbox = new QGraphicsLinearLayout(Qt::Vertical);
-    QGraphicsLinearLayout *hPilebox = 0;
 
+    // If the number is < 0, then it means that we can give the option to make the area sorted
     if (numberCards < 0) {
-        hPilebox = new QGraphicsLinearLayout(Qt::Horizontal);
+        QGraphicsLinearLayout *hPilebox = new QGraphicsLinearLayout(Qt::Horizontal);
         QGraphicsLinearLayout *hFilterbox = new QGraphicsLinearLayout(Qt::Horizontal);
 
         QGraphicsProxyWidget *sortByNameProxy = new QGraphicsProxyWidget;
@@ -57,16 +66,16 @@ ZoneViewWidget::ZoneViewWidget(Player *_player,
         QGraphicsProxyWidget *pileViewProxy = new QGraphicsProxyWidget;
         pileViewProxy->setWidget(&pileViewCheckBox);
         hPilebox->addItem(pileViewProxy);
-    }
 
-    if (_origZone->getIsShufflable() && (numberCards == -1)) {
-        shuffleCheckBox.setChecked(true);
-        QGraphicsProxyWidget *shuffleProxy = new QGraphicsProxyWidget;
-        shuffleProxy->setWidget(&shuffleCheckBox);
-        hPilebox->addItem(shuffleProxy);
-    }
+        if (_origZone->getIsShufflable() && numberCards == -1) {
+            shuffleCheckBox.setChecked(true);
+            QGraphicsProxyWidget *shuffleProxy = new QGraphicsProxyWidget;
+            shuffleProxy->setWidget(&shuffleCheckBox);
+            hPilebox->addItem(shuffleProxy);
+        }
 
-    vbox->addItem(hPilebox);
+        vbox->addItem(hPilebox);
+    }
 
     extraHeight = vbox->sizeHint(Qt::PreferredSize).height();
     resize(150, 150);
@@ -93,8 +102,7 @@ ZoneViewWidget::ZoneViewWidget(Player *_player,
     connect(zone, SIGNAL(wheelEventReceived(QGraphicsSceneWheelEvent *)), scrollBarProxy,
             SLOT(recieveWheelEvent(QGraphicsSceneWheelEvent *)));
 
-    // numberCard is the num of cards we want to reveal from an area. Ex: scry the top 3 cards.
-    // If the number is < 0 then it means that we can make the area sorted and we dont care about the order.
+    // only wire up sort options after creating ZoneViewZone, since it segfaults otherwise.
     if (numberCards < 0) {
         connect(&sortByNameCheckBox, &QCheckBox::QT_STATE_CHANGED, this, &ZoneViewWidget::processSortByName);
         connect(&sortByTypeCheckBox, &QCheckBox::QT_STATE_CHANGED, this, &ZoneViewWidget::processSortByType);

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