More doxygen header documentation

SleepLib/day.h

@@ -18,65 +18,134 @@ class OneTypePerDay
 
 class Machine;
 class Session;
+
+/*! \class Day
+    \brief Contains a list of all Sessions for single date, for a single machine
+    */
 class Day
 {
 public:
     Day(Machine *m);
     ~Day();
+
+    //! \brief Add Session to this Day object (called during Load)
     void AddSession(Session *s);
 
+    //! \brief Returns this machines type
     MachineType machine_type();
 
+    //! \brief Returns the count of all this days sessions' events for this day
     int count(ChannelID code);
+
+    //! \brief Returns the Minimum of all this sessions' events for this day
     EventDataType Min(ChannelID code);
+
+    //! \brief Returns the Maximum of all sessions' events for this day
     EventDataType Max(ChannelID code);
+
+    //! \brief Returns the Count-per-hour of all sessions' events for this day
     EventDataType cph(ChannelID code);
+
+    //! \brief Returns the Sum-per-hour of all this sessions' events for this day
     EventDataType sph(ChannelID code);
+
+    //! \brief Returns (and caches) the 90th Percentile of all this sessions' events for this day
     EventDataType p90(ChannelID code);
+
+    //! \brief Returns the Average of all this sessions' events for this day
     EventDataType avg(ChannelID code);
+
+    //! \brief Returns the Sum of all this sessions' events for this day
     EventDataType sum(ChannelID code);
+
+    //! \brief Returns the Time-Weighted Average of all this sessions' events for this day
     EventDataType wavg(ChannelID code);
+
+    //! \brief Returns a requested Percentile of all this sessions' events for this day
     EventDataType percentile(ChannelID code,EventDataType percentile);
 
+    //! \brief Returns if the cache contains SummaryType information about the requested code
     bool hasData(ChannelID code, SummaryType type);
 
-    QHash<ChannelID, EventDataType> m_p90; // 90% cache
+    //! \brief Cache for holding slow calculated 90th Percentile for this day
+    QHash<ChannelID, EventDataType> m_p90;
 
     //EventDataType percentile(ChannelID mc,double percent);
 
-    // Note, the following convert to doubles without considering the consequences fully.
+    // Note, the following convert to doubles without considering the consequences fully.?
+
+    //! \brief Returns the Average of all Sessions setting 'code' for this day
     EventDataType settings_avg(ChannelID code);
+
+    //! \brief Returns the Time-Weighted Average of all Sessions setting 'code' for this day
     EventDataType settings_wavg(ChannelID code);
+
+    //! \brief Returns the Sum of all Sessions setting 'code' for this day
     EventDataType settings_sum(ChannelID code);
+
+    //! \brief Returns the Minimum of all Sessions setting 'code' for this day
     EventDataType settings_min(ChannelID code);
+
+    //! \brief Returns the Maximum of all Sessions setting 'code' for this day
     EventDataType settings_max(ChannelID code);
 
+    //! \brief Returns the first session time of this day
     qint64 first() { return d_first; }
+
+    //! \brief Returns the last session time of this day
     qint64 last() { return d_last; }
+
+    //! \brief Sets the first session time of this day
     void setFirst(qint64 val) { d_first=val; }
+
+    //! \brief Sets the last session time of this day
     void setLast(qint64 val) { d_last=val; }
+
+    //! \brief Returns the last session time of this day for the supplied Channel code
     qint64 first(ChannelID code);
+
+    //! \brief Returns the last session time of this day for the supplied Channel code
     qint64 last(ChannelID code);
 
+    //! \brief Returns the total time in milliseconds for this day
+    qint64 total_time();
 
-    qint64 total_time(); // in milliseconds
+    //! \brief Return the total time in decimal hours for this day
     EventDataType hours() { return double(total_time())/3600000.0; }
 
+    //! \brief Return the session indexed by i
     Session *operator [](int i) { return sessions[i]; }
 
+    //! \brief Return the first session as a QVector<Session*>::iterator
     QVector<Session *>::iterator begin() { return sessions.begin(); }
+    //! \brief Return the end session record as a QVector<Session*>::iterator
     QVector<Session *>::iterator end() { return sessions.end(); }
+
+    //! \brief Finds and returns the index of a session, otherwise -1 if it's not there
     int find(Session * sess) { return sessions.indexOf(sess); }
+
+    //! \brief Returns the number of Sessions in this day record
     int size() { return sessions.size(); }
+
     Machine *machine;
 
+    //! \brief Loads all Events files for this Days Sessions
     void OpenEvents();
+
+    //! \brief Returns this days sessions list
     QVector<Session *> & getSessions() { return sessions; }
+
+    //! \brief Returns true if this Day contains loaded Event Data for this channel.
     bool channelExists(ChannelID id);
+
+    //! \brief Returns true if this Day contains loaded Event Data or a cached count for this channel
     bool channelHasData(ChannelID id);
+
+    //! \brief Returns true if this day contains the supplied settings Channel id
     bool settingExists(ChannelID id);
 
 protected:
+    //! \brief A Vector containing all sessions for this day
     QVector<Session *> sessions;
     qint64 d_first,d_last;
 private:

SleepLib/machine.h

@@ -33,6 +33,9 @@ class Session;
 class Profile;
 class Machine;
 
+/*! \class SaveThread
+    \brief This class is used in the multithreaded save code.. It accelerates the indexing of summary data.
+    */
 class SaveThread:public QThread
 {
     Q_OBJECT
@@ -48,36 +51,81 @@ signals:
 };
 
 
+/*! \class Machine
+    \brief This Machine class is the Heart of SleepyLib, representing a single Machine and holding it's data
+
+    */
 class Machine
 {
 public:
+    /*! \fn Machine(Profile *p,MachineID id=0);
+        \brief Constructs a Machine object in Profile p, and with MachineID id
+
+        If supplied MachineID is zero, it will generate a new unused random one.
+        */
     Machine(Profile *p,MachineID id=0);
     virtual ~Machine();
 
+    //! \brief Load all Machine summary data
     bool Load();
+    //! \brief Save all Sessions where changed bit is set.
     bool Save();
+
+    //! \brief Save individual session
     bool SaveSession(Session *sess);
+
+    //! \brief Deletes the crud out of all machine data in the SleepLib database
     bool Purge(int secret);
 
+    //! \brief Contains a secondary index of day data, containing just this machines sessions
     QMap<QDate,Day *> day;
+
+    //! \brief Contains all sessions for this machine, indexed by SessionID
     QHash<SessionID,Session *> sessionlist;
+
+    //! \brief List of text machine properties, like brand, model, etc...
     QHash<QString,QString> properties;
 
+    //! \brief Returns a pointer to a valid Session object if SessionID exists
     Session * SessionExists(SessionID session);
+
+    //! \brief Adds the session to this machine object, and the Master Profile list. (used during load)
     Day *AddSession(Session *s,Profile *p);
 
+    //! \brief Sets the Class of machine (Used to reference the particular loader that created it)
     void SetClass(QString t) { m_class=t; }
+
+    //! \brief Sets the type of machine, according to MachineType enum
     void SetType(MachineType t) { m_type=t; }
+
+    //! \brief Returns the Class of machine (Used to reference the particular loader that created it)
     const QString & GetClass() { return m_class; }
+
+    //! \brief Returns the type of machine, according to MachineType enum
     const MachineType & GetType() { return m_type; }
+
+    //! \brief Returns the machineID as a lower case hexadecimal string
     QString hexid() { return QString().sprintf("%08lx",m_id); }
+
+
+    //! \brief Unused, increments the most recent sessionID
     SessionID CreateSessionID() { return highest_sessionid+1; }
+
+    //! \brief Returns this objects MachineID
     const MachineID & id() { return m_id; }
+
+    //! \brief Returns the date of the first loaded Session
     const QDate & FirstDay() { return firstday; }
+
+    //! \brief Returns the date of the most recent loaded Session
     const QDate & LastDay() { return lastday; }
 
+    //! \brief Grab the next task in the multithreaded save code
     Session *popSaveList();
+
+    //! \brief The list of sessions that need saving (for multithreaded save code)
     QList<Session *> m_savelist;
+
     volatile int savelistCnt;
     int savelistSize;
     QMutex savelistMutex;
@@ -95,6 +143,10 @@ protected:
     bool firstsession;
 };
 
+
+/*! \class CPAP
+    \brief A CPAP classed machine object.. These are only really for show
+    */
 class CPAP:public Machine
 {
 public:
@@ -102,6 +154,10 @@ public:
     virtual ~CPAP();
 };
 
+
+/*! \class Oximeter
+    \brief An Oximeter classed machine object.. These are only really for show
+    */
 class Oximeter:public Machine
 {
 public:
@@ -110,6 +166,9 @@ public:
 protected:
 };
 
+/*! \class SleepStage
+    \brief A SleepStage classed machine object.. These are only really for show
+    */
 class SleepStage:public Machine
 {
 public:
@@ -118,6 +177,7 @@ public:
 protected:
 };
 
+//! \brief Calculate the timezone Offset in milliseconds between system timezone and UTC
 qint64 timezoneOffset();
 
 #endif // MACHINE_H

SleepLib/session.cpp

@@ -960,15 +960,15 @@ EventDataType Session::wavg(ChannelID id)
     return v;
 }
 
-EventList * Session::AddEventList(QString chan, EventListType et,EventDataType gain,EventDataType offset,EventDataType min, EventDataType max,EventDataType rate,bool second_field)
+EventList * Session::AddEventList(ChannelID code, EventListType et,EventDataType gain,EventDataType offset,EventDataType min, EventDataType max,EventDataType rate,bool second_field)
 {
-    schema::Channel * channel=&schema::channel[chan];
+    schema::Channel * channel=&schema::channel[code];
     if (!channel) {
         qWarning() << "Channel" << chan << "does not exist!";
         //return NULL;
     }
     EventList * el=new EventList(et,gain,offset,min,max,rate,second_field);
-    eventlist[chan].push_back(el);
+    eventlist[code].push_back(el);
     //s_machine->registerChannel(chan);
     return el;
 }

SleepLib/session.h

@@ -18,44 +18,81 @@
 //class EventList;
 class Machine;
 
+/*! \class Session
+    \brief Contains a single Sessions worth of machine event/waveform information.
 
+    This class also contains all the primary database logic for SleepLib
+    */
 class Session
 {
 public:
+    /*! \fn Session(Machine *,SessionID);
+        \brief Create a session object belonging to Machine, with supplied SessionID
+        If sessionID is 0, the next in sequence will be picked
+        */
     Session(Machine *,SessionID);
     virtual ~Session();
 
+    //! \brief Stores the session in the directory supplied by path
     bool Store(QString path);
+
+    //! \brief Writes the Sessions Summary Indexes to filename, in SleepLibs custom data format.
     bool StoreSummary(QString filename);
+
+    //! \brief Writes the Sessions EventLists to filename, in SleepLibs custom data format.
     bool StoreEvents(QString filename);
+
     //bool Load(QString path);
+
+    //! \brief Loads the Sessions Summary Indexes from filename, from SleepLibs custom data format.
     bool LoadSummary(QString filename);
+
+    //! \brief Loads the Sessions EventLists from filename, from SleepLibs custom data format.
     bool LoadEvents(QString filename);
 
+    //! \brief Loads the events for this session when requested (only the summaries are loaded at startup)
     bool OpenEvents();
+
+    //! \brief Put the events away until needed again, freeing memory
     void TrashEvents();
 
+    //! \brief Search for Event code happening within dist milliseconds of supplied time (ms since epoch)
     bool SearchEvent(ChannelID code, qint64 time, qint64 dist=15000);
 
-
+    //! \brief Return the sessionID
     const SessionID & session() {
         return s_session;
     }
+
+    //! \brief Return the start of this sessions time range (in milliseconds since epoch)
     qint64 first() {
         return s_first;
     }
+
+    //! \brief Return the end of this sessions time range (in milliseconds since epoch)
     qint64 last() {
         return s_last;
     }
+
+    //! \brief Return the millisecond length of this session
     qint64 length() {
         return s_last-s_first;
     }
+
+    //! \brief Set this Sessions ID (Not does not update indexes)
     void SetSessionID(SessionID s) {
         s_session=s;
     }
+
+    //! \brief Moves all of this session data by offset d milliseconds
     void offsetSession(qint64 d);
+
+    //! \brief Just set the start of the timerange without comparing
     void really_set_first(qint64 d) { s_first=d; }
+
+    //! \brief Just set the end of the timerange without comparing
     void really_set_last(qint64 d) { s_last=d; }
+
     void set_first(qint64 d) {
         if (!s_first) s_first=d;
         else if (d<s_first) s_first=d;
@@ -69,21 +106,30 @@ public:
         else if (s_last<d) s_last=d;
     }
 
+    //! \brief Return Session Length in decimal hours
     double hours() {
         double t=(s_last-s_first)/3600000.0;
         return t;
     }
 
+    //! \brief Flag this Session as dirty, so Machine object can save it
     void SetChanged(bool val) {
         s_changed=val;
         s_events_loaded=val; // dirty hack putting this here
     }
+
+    //! \brief Return this Sessions dirty status
     bool IsChanged() {
         return s_changed;
     }
 
+    //! \brief Contains all the EventLists, indexed by ChannelID
     QHash<ChannelID,QVector<EventList *> > eventlist;
+
+    //! \brief Sessions Settings List, contianing single settings for this session.
     QHash<ChannelID,QVariant> settings;
+
+    // Session caches
     QHash<ChannelID,int> m_cnt;
     QHash<ChannelID,double> m_sum;
     QHash<ChannelID,EventDataType> m_avg;
@@ -112,36 +158,74 @@ public:
 
     int count(ChannelID id);
 
+    //! \brief Returns the Count of all events of type id between time range
     int rangeCount(ChannelID id, qint64 first,qint64 last);
+
+    //! \brief Returns the Sum of all events of type id between time range
     double rangeSum(ChannelID id, qint64 first,qint64 last);
+
+    //! \brief Returns the minimum of events of type id between time range
     EventDataType rangeMin(ChannelID id, qint64 first,qint64 last);
+
+    //! \brief Returns the maximum of events of type id between time range
     EventDataType rangeMax(ChannelID id, qint64 first,qint64 last);
 
+
+    //! \brief Returns (and caches) the Sum of all events of type id
     double sum(ChannelID id);
+
+    //! \brief Returns (and caches) the Average of all events of type id
     EventDataType avg(ChannelID id);
+
+    //! \brief Returns (and caches) the Time Weighted Average of all events of type id
     EventDataType wavg(ChannelID i);
+
+    //! \brief Returns (and caches) the Minimum of all events of type id
     EventDataType Min(ChannelID id);
+
+    //! \brief Returns (and caches) the Maximum of all events of type id
     EventDataType Max(ChannelID id);
+
+    //! \brief Returns (and caches) the 90th Percentile of all events of type id
     EventDataType p90(ChannelID id);
+
+    //! \brief Returns (and caches) the Count-Per-Hour of all events of type id
     EventDataType cph(ChannelID id);
+
+    //! \brief Returns (and caches) the Sum-Per-Hour of all events of type id
     EventDataType sph(ChannelID id);
 
+    //! \brief Returns (without caching) the requested Percentile of all events of type id
     EventDataType percentile(ChannelID id,EventDataType percentile);
 
+    //! \brief Returns true if the channel has events loaded, or a record of a count for when they are not
     bool channelExists(QString name);// { return (schema::channel.names.contains(name));}
 
     bool IsLoneSession() { return s_lonesession; }
     void SetLoneSession(bool b) { s_lonesession=b; }
+
+    //! \brief Sets the event file linked to the summary (during load, for ondemand loading)
     void SetEventFile(QString & filename) { s_eventfile=filename; }
 
+    //! \brief Update this sessions first time if it's less than the current record
     inline void updateFirst(qint64 v) { if (!s_first) s_first=v; else if (s_first>v) s_first=v; }
+
+    //! \brief Update this sessions latest time if it's more than the current record
     inline void updateLast(qint64 v) { if (!s_last) s_last=v; else if (s_last<v) s_last=v; }
 
+    //! \brief Returns (and caches) the first time for Channel code
     qint64 first(ChannelID code);
+
+    //! \brief Returns (and caches) the last time for Channel code
     qint64 last(ChannelID code);
 
+    //! \brief Regenerates the Session Index Caches, and calls the fun calculation functions
     void UpdateSummaries();
-    EventList * AddEventList(QString chan, EventListType et, EventDataType gain=1.0, EventDataType offset=0.0, EventDataType min=0.0, EventDataType max=0.0, EventDataType rate=0.0, bool second_field=false);
+
+    //! \brief Creates and returns a new EventList for the supplied Channel code
+    EventList * AddEventList(ChannelID code, EventListType et, EventDataType gain=1.0, EventDataType offset=0.0, EventDataType min=0.0, EventDataType max=0.0, EventDataType rate=0.0, bool second_field=false);
+
+    //! \brief Returns this sessions MachineID
     Machine * machine() { return s_machine; }
 protected:
     SessionID s_session;

common_gui.h

@@ -9,7 +9,10 @@
 
 #include <QLocale>
 
+//! \brief Gets the first day of week from the system locale, to show in the calendars.
 Qt::DayOfWeek firstDayOfWeekFromLocale();
+
+//! \brief Delay of ms milliseconds
 void sh_delay(int ms);
 
 #endif