Added documentation for ModelManager and WIUserSettings classes. Made some...

Added documentation for ModelManager and WIUserSettings classes. Made some change in the positioning of the sky-object categories in the category view of the QML UI.

kstars/tools/whatsinteresting/modelmanager.h

@@ -15,19 +15,53 @@
  *                                                                         *
  ***************************************************************************/
 
+#ifndef MODEL_MANAGER_H
+#define MODEL_MANAGER_H
+
 #include "skyobjlistmodel.h"
 #include "kstarsdata.h"
 #include "obsconditions.h"
 
+/**
+ * \class ModelManager
+ * \brief Manages models for QML listviews of different types of sky-objects.
+ * \author Samikshan Bairagya
+ */
 class ModelManager
 {
 public:
+    /**
+     * \enum ModelType
+     * \brief Model type for different types of sky-objects.
+     */
     enum ModelType {Planet_Model, Star_Model, Constellation_Model, Galaxy_Model, Cluster_Model, Nebula_Model};
+
+    /**
+     * \brief Constructor - Creates models for different sky-object types.
+     * \param obs   Pointer to an ObsConditions object.
+     */
     ModelManager(ObsConditions *obs);
+
+    /**
+     * \brief Destructor
+     */
     ~ModelManager();
+
+    /**
+     * \brief Updates sky-object list models.
+     */
     void updateModels(ObsConditions *obs);
+
+    /**
+     * \brief Clears all sky-objects list models.
+     */
     void resetModels();
 
+    /**
+     * \brief Returns model of given type.
+     * \return Pointer to SkyObjListModel of given type.
+     * \param type   Type of sky-object model to be returned.
+     */
     SkyObjListModel *returnModel (int type);
 
 private:
@@ -36,3 +70,5 @@ private:
     QStringList baseCatList, planetaryList, deepSkyList;
     QHash< ModelType, QList <SkyObject *> > initobjects;
 };
+
+#endif

kstars/tools/whatsinteresting/obsconditions.cpp

@@ -19,11 +19,11 @@
 #include "math.h"
 #include "kdebug.h"
 
-ObsConditions::ObsConditions(int bortle, double aperture, Equipment equip, EquipmentType eqType):
-    m_BortleClass(bortle), m_Aperture(aperture), m_Equip(equip), m_EqType(eqType)
+ObsConditions::ObsConditions(int bortle, double aperture, Equipment equip, TelescopeType telType):
+    m_BortleClass(bortle), m_Aperture(aperture), m_Equip(equip), m_TelType(telType)
 {
     // 't' parameter
-    switch (m_EqType)
+    switch (m_TelType)
     {
         case Reflector:
             m_tParam = 0.7;

kstars/tools/whatsinteresting/obsconditions.h

@@ -20,27 +20,86 @@
 
 #include "kstarsdata.h"
 
+/**
+ * \class ObsConditions
+ * This class deals with the observing conditions of the night sky.
+ * The limiting magntude is calculated depending on the equipment
+ * available to the user and the amount of light-pollution in the
+ * user's current observing location.
+ * \author Samikshan  Bairagya
+ */
 class ObsConditions
 {
 public:
+    /**
+     * \enum Equipment
+     * Equipment available to the user.
+     */
     enum Equipment { Telescope = 0, Binoculars, Both, None };
-    enum EquipmentType { Reflector = 0, Refractor };
-    ObsConditions(int bortle, double aperture, Equipment equip, EquipmentType eqType);
+
+    /**
+     * \enum TelescopeType
+     * Telescope Type (Reflector/Refractor)
+     */
+    enum TelescopeType { Reflector = 0, Refractor };
+
+    /**
+     * \brief Constructor
+     * \param bortle          Rating of light pollution based on the bortle dark-sky scale.
+     * \param aperture        Aperture of equipment.
+     * \param equip           Equipment available to the user.
+     * \param telType         Refelctor/Refractor type of telescope (if available)
+     */
+    ObsConditions(int bortle, double aperture, Equipment equip, TelescopeType telType);
+
+    /**
+     * \brief Destructor
+     */
     ~ObsConditions();
+
+    /**
+     * \brief Inline method to set available equipment
+     */
     inline void setEquipment(Equipment equip) { m_Equip = equip; }
-    inline void setEquipmentType(EquipmentType eqType) { m_EqType = eqType; }
+
+    /**
+     * \brief Inline method to set reflector/refractor type for telescope.
+     */
+    inline void setTelescopeType(TelescopeType telType) { m_TelType = telType; }
+
+    /**
+     * \brief Set limiting magnitude depending on Bortle dark-sky rating.
+     */
     void setLimMagnitude();
+
+    /**
+     * \brief Get optimum magnification under current observing conditions.
+     * \return Get optimum magnification under current observing conditions
+     */
     double getOptimumMAG();
+
+    /**
+     * \brief Get true limiting magnitude after taking equipment specifications into consideration.
+     * \return True limiting magnitude after taking equipment specifications into consideration.
+     */
     double getTrueMagLim();
+
+    /**
+     * \brief Evaluate visibility of sky-object based on current observing conditions.
+     * \return Visibility of sky-object based on current observing conditions as a boolean.
+     * \param geo       Geographic location of user.
+     * \param lst       Local standard time expressed as a dms object.
+     * \param so        SkyObject for which visibility is to be evaluated.
+     */
     bool isVisible(GeoLocation *geo, dms *lst, SkyObject *so);
 
 private:
-    int m_BortleClass;
-    Equipment m_Equip;
-    EquipmentType m_EqType;
-    double m_Aperture;
-    double m_tParam;
-    double m_LM;
+    int m_BortleClass;              ///Bortle dark-sky rating (from 1-9)
+    Equipment m_Equip;              ///Equipment type
+    TelescopeType m_TelType;        ///Telescope type
+    double m_Aperture;              ///Aperture of equipment
+    double m_tParam;                ///t-parameter corresponding to telescope type
+    double m_LM;                    ///Limiting Magnitude depending on m_BortleClass
 };
 
 #endif

kstars/tools/whatsinteresting/qml/wiview.qml

@@ -79,13 +79,13 @@ Rectangle {
 
                 Rectangle {
                     id: planetRect
-                    x: 110
-                    y: 34
+                    x: 128
+                    y: 35
                     width: planetText.width
                     height: planetText.height
                     color: "#00000000"
-                    anchors.verticalCenterOffset: -131
-                    anchors.horizontalCenterOffset: -48
+                    anchors.verticalCenterOffset: -130
+                    anchors.horizontalCenterOffset: -30
                     anchors.verticalCenter: parent.verticalCenter
                     anchors.horizontalCenter: parent.horizontalCenter
 
@@ -117,13 +117,13 @@ Rectangle {
 
                 Rectangle {
                     id: starRect
-                    x: 218
-                    y: 82
+                    x: 253
+                    y: 80
                     width: starText.width
                     height: starText.height
                     color: "#00000000"
-                    anchors.verticalCenterOffset: -83
-                    anchors.horizontalCenterOffset: 75
+                    anchors.verticalCenterOffset: -85
+                    anchors.horizontalCenterOffset: 87
                     anchors.horizontalCenter: parent.horizontalCenter
                     anchors.verticalCenter: parent.verticalCenter
 
@@ -155,13 +155,13 @@ Rectangle {
 
                 Rectangle {
                     id: conRect
-                    x: 54
-                    y: 118
+                    x: 71
+                    y: 113
                     width: conText.width
                     height: conText.height
                     color: "#00000000"
-                    anchors.verticalCenterOffset: -47
-                    anchors.horizontalCenterOffset: -80
+                    anchors.verticalCenterOffset: -52
+                    anchors.horizontalCenterOffset: -63
                     anchors.horizontalCenter: parent.horizontalCenter
                     anchors.verticalCenter: parent.verticalCenter
 

kstars/tools/whatsinteresting/wiusersettings.cpp

@@ -37,16 +37,16 @@ void WIUserSettings::makeConnections()
 
 void WIUserSettings::slotFinished(int)
 {
-    eq = noEquipCheck->isEnabled()
+    m_Equip = noEquipCheck->isEnabled()
             ? (ObsConditions::None)
             : (telescopeCheck->isChecked()
             ? (binocularsCheck->isChecked() ? ObsConditions::Both : ObsConditions::Telescope)
             : (binocularsCheck->isChecked() ? ObsConditions::Binoculars : ObsConditions::None));
 
-    type = (equipmentType->currentText()=="Reflector") ? ObsConditions::Reflector : ObsConditions::Refractor;
+    m_TelType = (equipmentType->currentText()=="Reflector") ? ObsConditions::Reflector : ObsConditions::Refractor;
 
     KStars *kstars = KStars::Instance();
-    kstars->showWI(new ObsConditions(bortleClass->value(), aperture->value(), eq, type));
+    kstars->showWI(new ObsConditions(bortleClass->value(), aperture->value(), m_Equip, m_TelType));
 }
 
 void WIUserSettings::slotTelescopeCheck(bool on)

kstars/tools/whatsinteresting/wiusersettings.h

@@ -15,8 +15,8 @@
  *                                                                         *
  ***************************************************************************/
 
-#ifndef WI_USER_SETTINGS
-#define WI_USER_SETTINGS
+#ifndef WI_USER_SETTINGS_H
+#define WI_USER_SETTINGS_H
 
 class WIView;
 
@@ -24,21 +24,47 @@ class WIView;
 #include <QWizard>
 #include "ui_wiusersettings.h"
 
+/**
+ * \class WIUserSettings
+ * \brief Wizard to set the location and equipment specifications for "What's Interesting..."
+ * \author Samikshan Bairagya
+ */
 class WIUserSettings : public QWizard, public Ui::WIUserSettingsUI
 {
     Q_OBJECT
 public:
+
+    /**
+     * \brief Constructor
+     */
     WIUserSettings(QWidget *parent = 0, Qt::WindowFlags flags = 0);
 
 public slots:
+
+    /**
+     * \brief Finish wizard and display QML interface for "What's Interesting..."
+     */
     void slotFinished(int);
+
+    /**
+     * \brief Telescope available - check/uncheck.
+     */
     void slotTelescopeCheck(bool);
+
+    /**
+     * \brief Binoculars available - check/uncheck.
+     */
     void slotBinocularsCheck(bool);
 
 private:
+
+    /**
+     * \brief Make connections between signals and corresponding slots.
+     */
     void makeConnections();
-    ObsConditions::Equipment eq;
-    ObsConditions::EquipmentType type;
+
+    ObsConditions::Equipment m_Equip;
+    ObsConditions::TelescopeType m_TelType;
     WIView *m_WI;
 };