From 69c05a5252388cdbddd3b62eb66813603aea8c8a Mon Sep 17 00:00:00 2001
From: julien <julien>
Date: Sun, 21 Mar 2010 20:53:28 +0000
Subject: [PATCH] Added some comments on new communication classes

git-svn-id: svn://svn.openpilot.org/OpenPilot/trunk@368 ebee16cc-31ac-478f-84a7-5cbb03baadba
---
 .../plugins/coreplugin/connectionmanager.cpp  | 21 ++++++++++++++++++
 ground/src/plugins/coreplugin/iconnection.h   | 22 +++++++++++++++++++
 ground/src/plugins/rawhid/rawhid.h            |  4 ++++
 ground/src/plugins/rawhid/rawhidplugin.cpp    |  1 -
 ground/src/plugins/rawhid/rawhidplugin.h      | 12 ++++++++++
 5 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/ground/src/plugins/coreplugin/connectionmanager.cpp b/ground/src/plugins/coreplugin/connectionmanager.cpp
index 14f58b6c2..25421d0df 100644
--- a/ground/src/plugins/coreplugin/connectionmanager.cpp
+++ b/ground/src/plugins/coreplugin/connectionmanager.cpp
@@ -97,6 +97,9 @@ void ConnectionManager::init()
                      this, SLOT(aboutToRemoveObject(QObject*)));
 }
 
+/**
+*   Slot called when a plugin added an object to the core pool
+*/
 void ConnectionManager::objectAdded(QObject *obj)
 {
     //Check if a plugin added a connection object to the pool
@@ -118,6 +121,9 @@ void ConnectionManager::aboutToRemoveObject(QObject *obj)
 {
 }
 
+/**
+*   Slot called when the user pressed the connect/disconnect button
+*/
 void ConnectionManager::onConnectPressed()
 {
     if(!m_deviceConnected)
@@ -157,6 +163,9 @@ void ConnectionManager::onConnectPressed()
     emit deviceDisconnected();
 }
 
+/**
+*   Find a device by its displayed (visible on screen) name
+*/
 devListItem ConnectionManager::findDevice(const QString &displayedName)
 {
     foreach(devListItem d, m_devList)
@@ -172,6 +181,10 @@ devListItem ConnectionManager::findDevice(const QString &displayedName)
     return d;
 }
 
+/**
+*   Unregister all devices from one connection plugin
+*   \param[in] connection Connection type that you want to forget about :)
+*/
 void ConnectionManager::unregisterAll(IConnection *connection)
 {
     for(QLinkedList<devListItem>::iterator iter = m_devList.begin();
@@ -184,6 +197,9 @@ void ConnectionManager::unregisterAll(IConnection *connection)
     }
 }
 
+/**
+*   Register a device from one connection plugin
+*/
 void ConnectionManager::registerDevice(IConnection *conn, const QString &devN, const QString &disp)
 {
     devListItem d;
@@ -194,6 +210,11 @@ void ConnectionManager::registerDevice(IConnection *conn, const QString &devN, c
     m_devList.append(d);
 }
 
+/**
+*   A device plugin notified us that its device list has changed
+*   (eg: user plug/unplug a usb device)
+*   \param[in] connection Connection type which signaled the update
+*/
 void ConnectionManager::devChanged(IConnection *connection)
 {
     //remove all registered devices
diff --git a/ground/src/plugins/coreplugin/iconnection.h b/ground/src/plugins/coreplugin/iconnection.h
index 6d72018d1..f674450d7 100644
--- a/ground/src/plugins/coreplugin/iconnection.h
+++ b/ground/src/plugins/coreplugin/iconnection.h
@@ -37,19 +37,41 @@
 
 namespace Core {
 
+/**
+*   An IConnection object define a "type of connection",
+*   for instance USB, Serial, Network, ...
+*/
 class CORE_EXPORT IConnection : public QObject
 {
     Q_OBJECT
 
 public:
+    /**
+    *   Return the list of devices found on the system
+    */
     virtual QStringList availableDevices() = 0;
+
+    /**
+    *   Open a device, and return a QIODevice interface from it
+    */
     virtual QIODevice *openDevice(const QString &deviceName) = 0;
+
     virtual void closeDevice(const QString &deviceName) {};
 
+    /**
+    *   Connection type name "USB HID"
+    */
     virtual QString connectionName() = 0;
+
+    /**
+    *   Short name to display in a combo box
+    */
     virtual QString shortName() {return connectionName();}
 
 signals:
+    /**
+    *   Available devices list has changed, signal it to connection manager (and whoever wants to know)
+    */
     void availableDevChanged(IConnection *);
 };
 
diff --git a/ground/src/plugins/rawhid/rawhid.h b/ground/src/plugins/rawhid/rawhid.h
index cf2056921..d57b850ac 100644
--- a/ground/src/plugins/rawhid/rawhid.h
+++ b/ground/src/plugins/rawhid/rawhid.h
@@ -33,6 +33,10 @@
 
 #include "pjrc_rawhid.h"
 
+/**
+*   The actual IO device that will be used to communicate
+*   with the board.
+*/
 class RAWHID_EXPORT RawHID : public QIODevice
 {
 public:
diff --git a/ground/src/plugins/rawhid/rawhidplugin.cpp b/ground/src/plugins/rawhid/rawhidplugin.cpp
index 56c6d6d63..51c192d30 100644
--- a/ground/src/plugins/rawhid/rawhidplugin.cpp
+++ b/ground/src/plugins/rawhid/rawhidplugin.cpp
@@ -37,7 +37,6 @@
 #include "rawhid_const.h"
 
 
-
 RawHIDEnumerationThread::RawHIDEnumerationThread(RawHIDConnection *rawhid)
     : m_rawhid(rawhid),
     m_running(true)
diff --git a/ground/src/plugins/rawhid/rawhidplugin.h b/ground/src/plugins/rawhid/rawhidplugin.h
index 183ce4091..df0d9103d 100644
--- a/ground/src/plugins/rawhid/rawhidplugin.h
+++ b/ground/src/plugins/rawhid/rawhidplugin.h
@@ -39,6 +39,12 @@
 class IConnection;
 class RawHIDConnection;
 
+
+/**
+*   Helper thread to check on device connection/disconnection
+*   Underlying HID library is not really easy to use,
+*   so we have to poll for device modification in a separate thread
+*/
 class RAWHID_EXPORT RawHIDEnumerationThread : public QThread
 {
     Q_OBJECT
@@ -56,6 +62,12 @@ protected:
     bool m_running;
 };
 
+
+/**
+*   Define a connection via the IConnection interface
+*   Plugin will add a instance of this class to the pool,
+*   so the connection manager can use it.
+*/
 class RAWHID_EXPORT RawHIDConnection
     : public Core::IConnection
 {