Added some comments on new communication classes

git-svn-id: svn://svn.openpilot.org/OpenPilot/trunk@368 ebee16cc-31ac-478f-84a7-5cbb03baadba

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

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 *);
 };
 

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:

ground/src/plugins/rawhid/rawhidplugin.cpp

@@ -37,7 +37,6 @@
 #include "rawhid_const.h"
 
 
-
 RawHIDEnumerationThread::RawHIDEnumerationThread(RawHIDConnection *rawhid)
     : m_rawhid(rawhid),
     m_running(true)

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
 {