Restructure doc comments and make hard-coded strings translatable

src/keys/YkChallengeResponseKey.cpp

@@ -27,6 +27,7 @@
 #include "keys/drivers/YubiKey.h"
 
 #include <QDebug>
+#include <QObject>
 
 YkChallengeResponseKey::YkChallengeResponseKey(int slot,
                                                bool blocking)
@@ -58,10 +59,12 @@ bool YkChallengeResponseKey::challenge(const QByteArray& chal, int retries)
         return true;
     }
 
-    /* If challenge failed, retry to detect YubiKeys int the event the YubiKey
+    /* If challenge failed, retry to detect YubiKeys in the event the YubiKey
      *  was un-plugged and re-plugged */
     while (retries > 0) {
+#ifdef QT_DEBUG
         qDebug() << "Attempt" << retries << "to re-detect YubiKey(s)";
+#endif
         retries--;
 
         if (YubiKey::instance()->init() != true) {
@@ -79,13 +82,13 @@ bool YkChallengeResponseKey::challenge(const QByteArray& chal, int retries)
 QString YkChallengeResponseKey::getName() const
 {
     unsigned int serial;
-    QString fmt("YubiKey[%1] Challenge Response - Slot %2 - %3");
+    QString fmt(QObject::tr("YubiKey[%1] Challenge Response - Slot %2 - %3"));
 
     YubiKey::instance()->getSerial(serial);
 
     return fmt.arg(QString::number(serial),
                    QString::number(m_slot),
-                   (m_blocking) ? "Press" : "Passive");
+                   (m_blocking) ? QObject::tr("Press") : QObject::tr("Passive"));
 }
 
 bool YkChallengeResponseKey::isBlocking() const

src/keys/drivers/YubiKey.cpp

@@ -29,9 +29,8 @@
 
 #include "YubiKey.h"
 
-/* Cast the void pointer from the generalized class definition
+// Cast the void pointer from the generalized class definition
- * to the proper pointer type from the now included system headers
+// to the proper pointer type from the now included system headers
- */
 #define m_yk (static_cast<YK_KEY*>(m_yk_void))
 #define m_ykds (static_cast<YK_STATUS*>(m_ykds_void))
 
@@ -41,10 +40,6 @@ YubiKey::YubiKey() : m_yk_void(NULL), m_ykds_void(NULL)
 
 YubiKey* YubiKey::m_instance(Q_NULLPTR);
 
-/**
- * @brief YubiKey::instance - get instance of singleton
- * @return
- */
 YubiKey* YubiKey::instance()
 {
     if (!m_instance) {
@@ -54,20 +49,16 @@ YubiKey* YubiKey::instance()
     return m_instance;
 }
 
-/**
- * @brief YubiKey::init - initialize yubikey library and hardware
- * @return
- */
 bool YubiKey::init()
 {
-    /* Previously initalized */
+    // previously initialized
     if (m_yk != NULL && m_ykds != NULL) {
 
         if (yk_get_status(m_yk, m_ykds)) {
-            /* Still connected */
+            // Still connected
             return true;
         } else {
-            /* Initialized but not connected anymore, re-init */
+            // Initialized but not connected anymore, re-init
             deinit();
         }
     }
@@ -76,7 +67,7 @@ bool YubiKey::init()
         return false;
     }
 
-    /* TODO: handle multiple attached hardware devices, currently own one */
+    // TODO: handle multiple attached hardware devices
     m_yk_void = static_cast<void*>(yk_open_first_key());
     if (m_yk == NULL) {
         return false;
@@ -92,10 +83,6 @@ bool YubiKey::init()
     return true;
 }
 
-/**
- * @brief YubiKey::deinit - cleanup after init
- * @return true on success
- */
 bool YubiKey::deinit()
 {
     if (m_yk) {
@@ -111,9 +98,6 @@ bool YubiKey::deinit()
     return true;
 }
 
-/**
- * @brief YubiKey::detect - probe for attached YubiKeys
- */
 void YubiKey::detect()
 {
     if (init()) {
@@ -133,11 +117,6 @@ void YubiKey::detect()
     emit notFound();
 }
 
-/**
- * @brief YubiKey::getSerial - serial number of yubikey
- * @param serial
- * @return
- */
 bool YubiKey::getSerial(unsigned int& serial) const
 {
     if (!yk_get_serial(m_yk, 1, 0, &serial)) {
@@ -162,23 +141,7 @@ static inline QString printByteArray(const QByteArray& a)
 }
 #endif
 
-/**
+YubiKey::ChallengeResult YubiKey::challenge(int slot, bool mayBlock, const QByteArray& chal, QByteArray& resp) const
- * @brief YubiKey::challenge - issue a challenge
- *
- * This operation could block if the YubiKey requires a touch to trigger.
- *
- * TODO: Signal to the UI that the system is waiting for challenge response
- *       touch.
- *
- * @param slot YubiKey configuration slot
- * @param mayBlock operation is allowed to block
- * @param chal challenge input to YubiKey
- * @param resp response output from YubiKey
- * @return SUCCESS when successful
- */
-YubiKey::ChallengeResult YubiKey::challenge(int slot, bool mayBlock,
-                                            const QByteArray& chal,
-                                            QByteArray& resp) const
 {
     int yk_cmd = (slot == 1) ? SLOT_CHAL_HMAC1 : SLOT_CHAL_HMAC2;
     QByteArray paddedChal = chal;
@@ -188,7 +151,7 @@ YubiKey::ChallengeResult YubiKey::challenge(int slot, bool mayBlock,
         return ERROR;
     }
 
-    /* yk_challenge_response() insists on 64 byte response buffer */
+    // yk_challenge_response() insists on 64 byte response buffer */
     resp.resize(64);
 
     /* The challenge sent to the yubikey should always be 64 bytes for
@@ -239,7 +202,7 @@ YubiKey::ChallengeResult YubiKey::challenge(int slot, bool mayBlock,
         }
     }
 
-    /* Actual HMAC-SHA1 response is only 20 bytes */
+    // actual HMAC-SHA1 response is only 20 bytes
     resp.resize(20);
 
 #ifdef QT_DEBUG

src/keys/drivers/YubiKey.h

@@ -30,21 +30,52 @@ class YubiKey : public QObject
 public:
     enum ChallengeResult { ERROR = -1, SUCCESS = 0, WOULDBLOCK };
 
+    /**
+     * @brief YubiKey::instance - get instance of singleton
+     * @return instance
+     */
     static YubiKey* instance();
 
-    /** Initialize the underlying yubico libraries */
+    /**
+     * @brief YubiKey::init - initialize yubikey library and hardware
+     * @return true on success
+     */
     bool init();
+
+    /**
+     * @brief YubiKey::deinit - cleanup after init
+     * @return true on success
+     */
     bool deinit();
 
-    /** Issue a challenge to the hardware */
+    /**
+     * @brief YubiKey::challenge - issue a challenge
+     *
+     * This operation could block if the YubiKey requires a touch to trigger.
+     *
+     * TODO: Signal to the UI that the system is waiting for challenge response
+     *       touch.
+     *
+     * @param slot YubiKey configuration slot
+     * @param mayBlock operation is allowed to block
+     * @param chal challenge input to YubiKey
+     * @param resp response output from YubiKey
+     * @return true on success
+     */
     ChallengeResult challenge(int slot, bool mayBlock,
                               const QByteArray& chal,
                               QByteArray& resp) const;
 
-    /** Read the serial number from the hardware */
+    /**
+     * @brief YubiKey::getSerial - serial number of YubiKey
+     * @param serial serial number
+     * @return true on success
+     */
     bool getSerial(unsigned int& serial) const;
 
-    /** Start looking for attached hardware devices */
+    /**
+     * @brief YubiKey::detect - probe for attached YubiKeys
+     */
     void detect();
 
 Q_SIGNALS:
@@ -65,9 +96,9 @@ private:
     explicit YubiKey();
     static YubiKey* m_instance;
 
-    /* Create void ptr here to avoid ifdef header include mess */
+    // Create void ptr here to avoid ifdef header include mess
-    void *m_yk_void;
+    void* m_yk_void;
-    void *m_ykds_void;
+    void* m_ykds_void;
 
     Q_DISABLE_COPY(YubiKey)
 };