From 96fe438a91fd4b6fddaeabb60a15e0cd2becebc8 Mon Sep 17 00:00:00 2001
From: Bill Somerville <g4wjs@classdesign.com>
Date: Sat, 4 Jun 2016 14:59:01 +0000
Subject: [PATCH] Polish the Modes class and make it more robust

git-svn-id: svn+ssh://svn.code.sf.net/p/wsjt/wsjt/branches/wsjtx@6726 ab8295b8-cf94-4d9e-aec4-7959e3be5d79
---
 Modes.cpp |  9 ++++++++-
 Modes.hpp | 33 ++++++++++++++++++++++++++++++++-
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/Modes.cpp b/Modes.cpp
index 48ba03ee4..d4c4f84d6 100644
--- a/Modes.cpp
+++ b/Modes.cpp
@@ -1,12 +1,16 @@
 #include "Modes.hpp"
 
+#include <algorithm>
+
 #include <QString>
 #include <QVariant>
+#include <QModelIndex>
 
 #include "moc_Modes.cpp"
 
 namespace
 {
+  // human readable strings for each Mode enumeration value
   char const * const mode_names[] =
   {
     "",
@@ -19,11 +23,14 @@ namespace
     "JTMSK",
     "MSK144"
   };
+  std::size_t constexpr mode_names_size = sizeof (mode_names) / sizeof (mode_names[0]);
 }
 
 Modes::Modes (QObject * parent)
   : QAbstractListModel {parent}
 {
+  static_assert (mode_names_size == MODES_END_SENTINAL_AND_COUNT,
+                 "mode_names array must match Mode enumeration");
 }
 
 char const * Modes::name (Mode m)
@@ -33,7 +40,7 @@ char const * Modes::name (Mode m)
 
 auto Modes::value (QString const& s) -> Mode
 {
-  auto end = mode_names + sizeof (mode_names) / sizeof (mode_names[0]);
+  auto end = mode_names + mode_names_size;
   auto p = std::find_if (mode_names, end
                          , [&s] (char const * const name) {
                            return name == s;
diff --git a/Modes.hpp b/Modes.hpp
index 98e146586..0dd5b4b46 100644
--- a/Modes.hpp
+++ b/Modes.hpp
@@ -5,6 +5,26 @@
 
 #include "qt_helpers.hpp"
 
+class QString;
+class QVariant;
+class QModelIndex;
+
+//
+// Class Modes - Qt model that implements a list of data modes
+//
+//
+// Responsibilities
+//
+// 	Provides  a  single column  list  model  that contains  the  human
+// 	readable string version of the data mode in the display role. Also
+// 	provided  is a  translatable  column header  string  and tool  tip
+// 	string.
+//
+//
+// Collaborations
+//
+// 	Implements a concrete sub-class of the QAbstractListModel class.
+//
 class Modes final
   : public QAbstractListModel
 {
@@ -12,9 +32,14 @@ class Modes final
   Q_ENUMS (Mode)
 
 public:
+  //
+  // This enumeration contains the supported modes, to complement this
+  // an array of human readable strings in the implementation
+  // (Modes.cpp) must be maintained in parallel.
+  //
   enum Mode
   {
-    NULL_MODE,
+    NULL_MODE,                  // NULL Mode - matches with all modes
     JT65,
     JT9,
     JT4,
@@ -29,6 +54,7 @@ public:
 
   explicit Modes (QObject * parent = nullptr);
 
+  // translate between enumeration and human readable strings
   static char const * name (Mode);
   static Mode value (QString const&);
 
@@ -41,7 +67,12 @@ public:
   QVariant headerData (int section, Qt::Orientation, int = Qt::DisplayRole) const override;
 };
 
+// Qt boilerplate to make the Modes::Mode enumeration a type that can
+// be streamed and queued as a signal argument as well as showing the
+// human readable string when output to debug streams.
 #if QT_VERSION < 0x050500
+// Qt 5.6 introduces the Q_ENUM macro which automatically registers
+// the meta-type
 Q_DECLARE_METATYPE (Modes::Mode);
 #endif