From 9e705790eda69f0eeee19b68565fdca21a06450f Mon Sep 17 00:00:00 2001
From: Petr Kubiznak <kubiznak.petr@gmail.com>
Date: Fri, 1 Apr 2011 09:44:29 +0200
Subject: [PATCH] field.h: Comments refactored into doxygen form.

---
 core/field.cpp |   4 +-
 core/field.h   | 123 +++++++++++++++++++++++++++++++++++----------------------
 2 files changed, 77 insertions(+), 50 deletions(-)
 rewrite core/field.h (62%)

diff --git a/core/field.cpp b/core/field.cpp
index 5ae880b..d9cc79d 100644
--- a/core/field.cpp
+++ b/core/field.cpp
@@ -56,7 +56,7 @@ void Field::setMark(bool setVal) {
 
 /* -------------------------------------------------------------------------- */
 
-/* vraci true, pokud je zadane pole neodkryte - neni nastaven covered-bit */
+/* vraci true, pokud je zadane pole neodkryte - je nastaven covered-bit */
 bool Field::isCovered(void) const {
   return data & MASK_COVERED;
 }
@@ -73,7 +73,7 @@ void Field::setCovered(bool setVal) {
 /* vrati pocet min v okoli pole;
  * v pripade, ze je pole zakryte, vyhazuje vyjimku s kodem ERR_ACC_FORBIDDEN */
 int Field::getNeighboursCnt(void) const {
-  if(isCovered()) throw GeneralException(ERR_ACC_FORBIDDEN, "");
+  if(isCovered()) throw AccessForbiddenException("");
   else return data & MASK_NEIGHBOURS;
 }
 
diff --git a/core/field.h b/core/field.h
dissimilarity index 62%
index 8fd87c5..565797a 100644
--- a/core/field.h
+++ b/core/field.h
@@ -1,48 +1,75 @@
-/* 
- * File:   field.h
- * Author: Petr Kubizňák
- * Purpose:Trida implementujici jedno policko v hracim poli.
- */
-
-#ifndef _FIELD_H
-#define	_FIELD_H
-
-#define MASK_COVERED      0x20
-
-class Field {
-protected:
-    unsigned char data;
-
-    /* nastavi covered-bit */
-    inline void setCovered(bool setVal);
-
-public:
-    /* implicitni konstruktor (vytvori zakryte pole bez miny a oznaceni */
-    Field(unsigned char val = MASK_COVERED);
-    ~Field(void);
-
-    /* vraci true, pokud je nastaven mine-bit */
-    bool hasMine(void) const;
-    /* danemu poli nastavi mine-bit na hodnotu setVal */
-    void setMine(bool setVal);
-    /* vraci true, pokud je nastaven mark-bit (pole oznaceno jako zaminovane) */
-    bool hasMark(void) const;
-    /* danemu poli nastavi mark-bit podle hodnoty setVal */
-    void setMark(bool setVal);
-    /* vraci true, pokud je zadane pole neodkryte - neni nastaven covered-bit */
-    bool isCovered(void) const;
-    /* odkryje zadane pole a vrati pocet min v jeho okoli */
-    int uncover(void);
-    /* nastavi pocet min v okolnich polich */
-    void setNeighboursCnt(int count);
-    /* vrati pocet min v okoli pole;
-     * v pripade, ze je pole zakryte, vyhazuje vyjimku s kodem ERR_ACC_FORBIDDEN */
-    int getNeighboursCnt(void) const;
-
-    /* pretypovani pole na int vraci vnitrni reprezentaci - hodnotu var "data" */
-    operator int (void) const;
-    
-};
-
-#endif	/* _FIELD_H */
-
+/** ************************************************************************************************
+ *  @file board.h
+ *  
+ *  @brief One field of game board.
+ *  
+ *  Data structure representing one field, provides protected and unprotected access.
+ *  
+ *  @author Petr Kubiznak <kubiznak.petr@gmail.com>
+ *  
+ *  @since 2009-11-??
+ *  
+ **************************************************************************************************/
+
+#ifndef _FIELD_H
+#define	_FIELD_H
+
+//**************************************************************************************************
+
+#define MASK_COVERED      0x20
+
+//**************************************************************************************************
+
+/** Implements data structure representing one field of the board. */
+class Field {
+protected:
+    unsigned char data;                                                         //!< data of the structure - bitfield of flags
+
+    /** Sets the covered-bit.
+     * @param setVal Use true to cover the field, false to uncover. */
+    inline void setCovered(bool setVal);
+
+public:
+    /** Creates new object of the class.
+     * @param val Bitfield content - be careful. Use default value to create implicit, covered field. */
+    Field(unsigned char val = MASK_COVERED);
+    /** Frees allocated resources. */
+    ~Field(void);
+
+    /** Checks whether the field contains mine.
+     * @return True if mine is present in the field, false otherwise. */
+    bool hasMine(void) const;
+    /** Sets, whether the field contains a mine.
+     * @setVal Use true to set mine, false to unset. */
+    void setMine(bool setVal);
+    /** Checks whether the field is user-marked as mined.
+     * @return True if field is marked, false otherwise. */
+    bool hasMark(void) const;
+    /** Sets the user-mark.
+     * @setVal Use true to mark as mined, false to unmark.
+     * @throw AccessForbiddenException if the field is already uncovered. */
+    void setMark(bool setVal);
+    /** Checks whether the field is covered.
+     * @return True if it is covered, false if uncovered. */
+    bool isCovered(void) const;
+    /** Uncovers the field.
+     * @return Number of mines hidden in field arround this one. */
+    int uncover(void);
+    /** Stores the number of mines hidden arround this field.
+     * @param count Number of hiden mines. */
+    void setNeighboursCnt(int count);
+    /** Gets the number of mines arround this field.
+     * @return Number of hiden mines.
+     * @throw AccessForbiddenException if the field is still covered. */
+    int getNeighboursCnt(void) const;
+
+    /** Casts the Field to int.
+     * @return The inner data representation, i.e. bitfield. */
+    operator int (void) const;
+    
+};
+
+//**************************************************************************************************
+
+#endif	/* _FIELD_H */
+
-- 
2.11.4.GIT