documentation

Author: juchi

card.cpp

@@ -25,6 +25,12 @@
 #include <iostream>
 #include <sstream>
 
+/*!
+ * \brief Constructor
+ * \param color The color of the card
+ * \param value The value of the card
+ * \param board The board of the game
+ */
 Card::Card(cardcolor color, cardvalue value, Board* board) : AbstractCardHolder()
 {
     mChild = 0;
@@ -44,21 +50,20 @@ Card::Card(cardcolor color, cardvalue value, Board* board) : AbstractCardHolder(
     mBoard->addItem(mProxy);
 }
 
-void Card::presents()
-{
-    std::cout << getLabel().toStdString() << std::endl;
-}
-
+/*!
+ * \brief Get a string for displaying the card's identity
+ * \return QString
+ */
 QString Card::getLabel()
 {
     return getValueName() + " of " + getColorName();
 }
 
-QPixmap Card::getWidgetPixmap()
-{
-    return mWidget->grab();
-}
-
+/*!
+ * \brief Change the parent of the card and update the position accordingly
+ * \param parent  The new parent
+ * \param animate If set to true, the position will change through an animation
+ */
 void Card::setParent(AbstractCardHolder* parent, bool animate)
 {
     if (mParent) {
@@ -72,6 +77,10 @@ void Card::setParent(AbstractCardHolder* parent, bool animate)
     }
 }
 
+/*!
+ * \brief Get the number of cards stacked over this one
+ * \return int
+ */
 int Card::countChildren()
 {
     if (mChild == 0) {
@@ -80,16 +89,29 @@ int Card::countChildren()
     return mChild->countChildren() + 1;
 }
 
+/*!
+ * \brief Check if a card can be stacked over this one
+ * \param card The card to check
+ * \return boolean
+ */
 bool Card::canStackCard(Card* card)
 {
     return isStackable() && getChild() == 0 && card->isMovable() && isValidParentOf(card);
 }
 
+/*!
+ * \brief Check if the card can receive other cards over itself
+ * \return boolean
+ */
 bool Card::isStackable()
 {
     return mParent->isStackable();
 }
 
+/*!
+ * \brief Check if the card can be moved from its current spot
+ * \return boolean
+ */
 bool Card::isMovable()
 {
     if (mIsOnAceSpot) {
@@ -101,6 +123,11 @@ bool Card::isMovable()
     return isValidParentOf(mChild) && mChild->isMovable() && mBoard->hasEnoughFreecells(countChildren() + 1);
 }
 
+/*!
+ * \brief Check if a given card's color and value allows it to be stacked over this one
+ * \param card The card to check
+ * \return
+ */
 bool Card::isValidParentOf(Card* card)
 {
     if (card == 0) {
@@ -112,16 +139,30 @@ bool Card::isValidParentOf(Card* card)
     return getValue() - card->getValue() == 1 && card->getBlackRedColor() != getBlackRedColor();
 }
 
+/*!
+ * \brief The the "ace spot" flag of the card
+ * The flag is used for the stacking behaviour, as ace spot only receive card of the same colour
+ * in ascendant order
+ * \param on The new value
+ */
 void Card::setOnAceSpot(bool on)
 {
     mIsOnAceSpot = on;
 }
 
+/*!
+ * \brief Getter for the "ace spot" flag
+ * \return boolean
+ */
 bool Card::isOnAceSpot()
 {
     return mIsOnAceSpot;
 }
 
+/*!
+ * \brief Get the value of this card as a string
+ * \return QString
+ */
 QString Card::getValueName()
 {
     QString cardValue = "";
@@ -149,6 +190,10 @@ QString Card::getValueName()
     return cardValue;
 }
 
+/*!
+ * \brief Get the color of this card as a string
+ * \return QString
+ */
 QString Card::getColorName()
 {
     QString colorName = "";
@@ -181,6 +226,10 @@ cardcolor Card::getColor()
     return mColor;
 }
 
+/*!
+ * \brief Convert the color of the card to the "real" (red or black) color
+ * \return 1 or 2
+ */
 char Card::getBlackRedColor()
 {
     if (mColor == HEARTS || mColor == DIAMONDS) {
@@ -201,6 +250,10 @@ QPoint Card::getChildPosition()
     return QPoint(x, y);
 }
 
+/*!
+ * \brief Get the position of the card in board coordinates
+ * \return QPoint
+ */
 QPoint Card::getPosition()
 {
     return mPosition;
@@ -224,6 +277,10 @@ void Card::animatePosition(QPoint pos)
     }
 }
 
+/*!
+ * \brief Change the position of the card and its children to pos
+ * \param pos The new position
+ */
 void Card::setPosition(QPoint pos)
 {
     mPosition = pos;
@@ -233,6 +290,10 @@ void Card::setPosition(QPoint pos)
     }
 }
 
+/*!
+ * \brief Replace the card to its expected position
+ * \param animate Flag for animating the position update
+ */
 void Card::updatePosition(bool animate)
 {
     if (animate) {
@@ -243,6 +304,10 @@ void Card::updatePosition(bool animate)
     }
 }
 
+/*!
+ * \brief Get the minimum zindex for the card to be visible over all its children
+ * \return int
+ */
 int Card::getTopZIndex()
 {
     if (mChild) {
@@ -251,11 +316,20 @@ int Card::getTopZIndex()
     return getZIndex() + 1;
 }
 
+/*!
+ * \brief Getter for the zindex of the card
+ * \return int
+ */
 int Card::getZIndex()
 {
     return mProxy->zValue();
 }
 
+/*!
+ * \brief Set the zindex of the card
+ * \param index   The new value
+ * \param cascade If set to true, the children are also updated
+ */
 void Card::setZIndex(int index, bool cascade)
 {
     mProxy->setZValue(index);
@@ -269,11 +343,17 @@ void Card::resetZIndex()
     setZIndex(mParent->getZIndex() + 1);
 }
 
+/*!
+ * \brief Display the card
+ */
 void Card::show()
 {
     mWidget->show();
 }
 
+/*!
+ * \brief Hide the card
+ */
 void Card::hide()
 {
     mWidget->hide();
@@ -284,6 +364,10 @@ void Card::select()
     mBoard->selectCard(this);
 }
 
+/*!
+ * \brief Update the card design so it is selected or not
+ * \param selected The new sselected status
+ */
 void Card::setSelected(bool selected)
 {
     mSelected = selected;
@@ -294,11 +378,19 @@ void Card::setSelected(bool selected)
     }
 }
 
+/*!
+ * \brief Check if the card is selected
+ * \return boolean
+ */
 bool Card::isSelected()
 {
     return mSelected;
 }
 
+/*!
+ * \brief Attempt automatic move with this card
+ * \see Board::automaticMove()
+ */
 void Card::automaticMove()
 {
     mBoard->automaticMove(this);

card.h

@@ -30,11 +30,13 @@ class CardProxy;
 class Board;
 class QPixmap;
 
+/*!
+ * \brief A Card
+ */
 class Card : public AbstractCardHolder
 {
     Q_OBJECT
 public:
-    Card();
     Card(cardcolor color, cardvalue value, Board* board);
 
     void setParent(AbstractCardHolder*, bool = false);
@@ -49,9 +51,7 @@ class Card : public AbstractCardHolder
 
     QString getValueName();
     QString getColorName();
-    void presents();
     QString getLabel();
-    QPixmap getWidgetPixmap();
 
     cardvalue getValue();
     cardcolor getColor();

freecell.cpp

@@ -22,6 +22,10 @@
 
 #include <QFrame>
 
+/*!
+ * \brief Constructor
+ * \param board
+ */
 Freecell::Freecell(Board* board) : CardSpot(board)
 {
     mProxy = new CardSpotProxy(this);

freecell.h

@@ -22,6 +22,9 @@
 
 class Board;
 
+/*!
+ * \brief A Freecell for holding cards
+ */
 class Freecell : public CardSpot
 {
 public:

mainwindow.cpp

@@ -20,6 +20,10 @@
 #include <QMenuBar>
 #include <QApplication>
 
+/*!
+ * \brief Constructor
+ * \param parent The parent widget
+ */
 MainWindow::MainWindow(QWidget *parent) :
     QMainWindow(parent)
 {
@@ -38,12 +42,18 @@ MainWindow::MainWindow(QWidget *parent) :
     newGame();
 }
 
+/*!
+ * \brief Start a new game
+ */
 void MainWindow::newGame()
 {
     endGame();
     mBoard->dealCards();
 }
 
+/*!
+ * \brief Triggers the end of a game
+ */
 void MainWindow::endGame()
 {
     mBoard->collectCards();

mainwindow.h

@@ -22,6 +22,9 @@
 
 class Board;
 
+/*!
+ * \brief The MainWindow of the application
+ */
 class MainWindow : public QMainWindow
 {
     Q_OBJECT