# HG changeset patch
# User sheepluva
# Date 1335565477 -7200
# Node ID 1fe601a2761be0e94f4ff76bd9f80434cdfdfa85
# Parent  11f52445e8cd9c56b143126472a5c7fe44e1097c
MapModel: comments/docs, small tweaks

diff -r 11f52445e8cd -r 1fe601a2761b QTfrontend/model/MapModel.cpp
--- a/QTfrontend/model/MapModel.cpp	Fri Apr 27 23:17:11 2012 +0200
+++ b/QTfrontend/model/MapModel.cpp	Sat Apr 28 00:24:37 2012 +0200
@@ -27,20 +27,24 @@
 
 void MapModel::loadMaps()
 {
+    // this method resets the contents of this model (important to know for views).
     beginResetModel();
 
-
+    // we'll need the DataManager a few times, so let's get a reference to it
     DataManager & datamgr = DataManager::instance();
 
+    // fetch list of available maps
     QStringList maps =
         datamgr.entryList("Maps", QDir::AllDirs | QDir::NoDotAndDotDot);
 
+    // empty list, so that we can (re)fill it
     QStandardItemModel::clear();
 
     QList<QStandardItem *> genMaps;
     QList<QStandardItem *> missionMaps;
     QList<QStandardItem *> staticMaps;
 
+    // add generated/handdrawn maps to list
     // TODO: icons for these
 
     genMaps.append(
@@ -50,10 +54,13 @@
     genMaps.append(
         infoToItem(QIcon(), QComboBox::tr("hand drawn map..."), HandDrawnMap, "+drawn+"));
 
-
+    // only 2 map relate files are relevant:
+    // - the cfg file that contains the settings/info of the map
+    // - the lua file - if it exists it's a mission, otherwise it isn't
     QFile mapLuaFile;
     QFile mapCfgFile;
 
+    // add mission/static maps to lists
     foreach (QString map, maps)
     {
         mapCfgFile.setFileName(
@@ -69,30 +76,41 @@
             quint32 limit = 0;
             QString scheme;
             QString weapons;
+            // if there is a lua file for this map, then it's a mission
             bool isMission = mapLuaFile.exists();
             MapType type = isMission?MissionMap:StaticMap;
 
+            // load map info from file
             QTextStream input(&mapCfgFile);
             input >> theme;
             input >> limit;
-            input >> scheme;
-            input >> weapons;
+            if (isMission) { // scheme and weapons are only relevant for missions
+                input >> scheme;
+                input >> weapons;
+            }
             mapCfgFile.close();
 
+            // let's use some semi-sane hedgehog limit, rather than none
             if (limit == 0)
                 limit = 18;
 
 
-            if (scheme.isEmpty())
-                scheme = "locked";
-            else
-                scheme.replace("_", " ");
+            // the default scheme/weaponset for missions.
+            // if empty we assume the map sets these internally -> locked
+            if (isMission)
+            {
+                if (scheme.isEmpty())
+                    scheme = "locked";
+                else
+                    scheme.replace("_", " ");
 
-            if (weapons.isEmpty())
-                weapons = "locked";
-            else
-                weapons.replace("_", " ");
+                if (weapons.isEmpty())
+                    weapons = "locked";
+                else
+                    weapons.replace("_", " ");
+            }
 
+            // add a mission caption prefix to missions
             if (isMission)
             {
                 // TODO: icon
@@ -102,9 +120,11 @@
             else
                 caption = map;
 
+            // we know everything there is about the map, let's get am item for it
             QStandardItem * item = infoToItem(
                 QIcon(), caption, type, map, theme, limit, scheme, weapons);
 
+            // append item to the list
             if (isMission)
                 missionMaps.append(item);
             else
@@ -114,12 +134,16 @@
 
     }
 
+    // update mission count member
     m_nMissions = missionMaps.size();
 
+    // define a separator item
     QStandardItem separator("---");
     separator.setData(QLatin1String("separator"), Qt::AccessibleDescriptionRole);
     separator.setFlags(separator.flags() & ~( Qt::ItemIsEnabled | Qt::ItemIsSelectable ) );
 
+    // create list:
+    // generated+handdrawn maps, 2 saperators, missions, 1 separator, static maps
     QList<QStandardItem * > items;
     items.append(genMaps);
     items.append(separator.clone());
@@ -128,8 +152,10 @@
     items.append(separator.clone());
     items.append(staticMaps);
 
+    // store list contents in the item model
     QStandardItemModel::appendColumn(items);
 
+
     endResetModel();
 }
 
diff -r 11f52445e8cd -r 1fe601a2761b QTfrontend/model/MapModel.h
--- a/QTfrontend/model/MapModel.h	Fri Apr 27 23:17:11 2012 +0200
+++ b/QTfrontend/model/MapModel.h	Sat Apr 28 00:24:37 2012 +0200
@@ -54,27 +54,45 @@
             StaticMap
         };
 
+        /// a struct for holding the attributes of a map.
         struct MapInfo
         {
-            MapType type;
-            QString name;
-            QString theme;
-            quint32 limit;
-            QString scheme;
-            QString weapons;
+            MapType type; ///< The map-type
+            QString name; ///< The internal name.
+            QString theme; ///< The theme to be used. (can be empty)
+            quint32 limit; ///< The maximum allowed number of hedgehogs.
+            QString scheme; ///< Default scheme name or "locked", for mission-maps.
+            QString weapons; ///< Default weaponset name or "locked", for missions-maps.
         };
 
+        /**
+         * @brief Returns the number of available mission maps.
+         * @return mission map count.
+         */
         int missionCount() const;
 
 
     public slots:
-        /// reloads the maps from the DataManager
+        /// reloads the maps using the DataManager
         void loadMaps();
 
 
     private:
-        int m_nMissions;
+        int m_nMissions; ///< used to keep track of the mission amount
 
+        /**
+         * @brief Creates a QStandardItem, that holds the map info and item appearance.
+         * The used role for the data is Qt::UserRole + 1.
+         * @param icon the icon to be displayed (can be an empty QIcon()).
+         * @param caption the text to be displayed.
+         * @param type the type of the map.
+         * @param name the internal name of the map.
+         * @param theme the theme of the map (or empty if none).
+         * @param limit the hedgehog limit of the map.
+         * @param scheme mission map: default scheme name or "locked".
+         * @param weapons mission map: default weaponset name or "locked".
+         * @return pointer to item representing the map info: at Qt::UserRole + 1.
+         */
         QStandardItem * infoToItem(
             const QIcon & icon,
             const QString caption,