1 files changed, 102 insertions, 6 deletions

diff --git a/libopie/odevice.cpp b/libopie/odevice.cpp
index 9b2a954..8f954b1 100644
--- a/libopie/odevice.cpp
+++ b/libopie/odevice.cpp
@@ -40,33 +40,33 @@
 #include <qwindowsystem_qws.h>
 
 
 // _IO and friends are only defined in kernel headers ...
 
 #define OD_IOC(dir,type,number,size)    (( dir << 30 ) | ( type << 8 ) | ( number ) | ( size << 16 ))
 
 #define OD_IO(type,number)              OD_IOC(0,type,number,0)
 #define OD_IOW(type,number,size)        OD_IOC(1,type,number,sizeof(size))
 #define OD_IOR(type,number,size)        OD_IOC(2,type,number,sizeof(size))
 #define OD_IORW(type,number,size)       OD_IOC(3,type,number,sizeof(size))
 
 using namespace Opie;
 
 class ODeviceData {
 public:
-        bool m_qwsserver;
+        bool m_qwsserver : 1;
 
         QString m_vendorstr;
         OVendor m_vendor;
 
         QString m_modelstr;
         OModel m_model;
 
         QString m_systemstr;
         OSystem m_system;
 
         QString m_sysverstr;
 
         Transformation m_rotation;
 
         QValueList <ODeviceButton> *m_buttons;
         uint                        m_holdtime;
@@ -257,32 +257,35 @@ ODevice::ODevice ( )
 
         d-> m_holdtime = 1000; // 1000ms
         d-> m_buttons = 0;
 }
 
 void ODevice::systemMessage ( const QCString &msg, const QByteArray & )
 {
         if ( msg == "deviceButtonMappingChanged()" ) {
                 reloadButtonMapping ( );
         }
 }
 
 void ODevice::init ( )
 {
 }
 
+/**
+ * This method initialises the  button mapping
+ */
 void ODevice::initButtons ( )
 {
         if ( d-> m_buttons )
                 return;
 
         // Simulation uses iPAQ 3660 device buttons
 
         qDebug ( "init Buttons" );
         d-> m_buttons = new QValueList <ODeviceButton>;
 
         for ( uint i = 0; i < ( sizeof( ipaq_buttons ) / sizeof( i_button )); i++ ) {
                 i_button *ib = ipaq_buttons + i;
                 ODeviceButton b;
 
                 if (( ib-> model & Model_iPAQ_H36xx ) == Model_iPAQ_H36xx ) {
                         b. setKeycode ( ib-> code );
@@ -300,33 +303,43 @@ void ODevice::initButtons ( )
 }
 
 ODevice::~ODevice ( )
 {
         delete d;
 }
 
 bool ODevice::setSoftSuspend ( bool /*soft*/ )
 {
         return false;
 }
 
 //#include <linux/apm_bios.h>
 
 #define APM_IOC_SUSPEND          OD_IO( 'A', 2 )
 
-
+/**
+ * This method will try to suspend the device
+ * It only works if the user is the QWS Server and the apm application
+ * is installed.
+ * It tries to suspend and then waits some time cause some distributions
+ * do have asynchronus apm implementations.
+ * This method will either fail and return false or it'll suspend the
+ * device and return once the device got woken up
+ *
+ * @return if the device got suspended
+ */
 bool ODevice::suspend ( )
 {
         if ( !d-> m_qwsserver ) // only qwsserver is allowed to suspend
                 return false;
 
         if ( d-> m_model == Model_Unknown ) // better don't suspend in qvfb / on unkown devices
                 return false;
 
         bool res = false;
 
         struct timeval tvs, tvn;
         ::gettimeofday ( &tvs, 0 );
 
         ::sync ( ); // flush fs caches
         res = ( ::system ( "apm --suspend" ) == 0 );
 
@@ -341,177 +354,260 @@ bool ODevice::suspend ( )
                 } while ((( tvn. tv_sec - tvs. tv_sec ) * 1000 + ( tvn. tv_usec - tvs. tv_usec ) / 1000 ) < 1500 );
         }
 
         return res;
 }
 
 //#include <linux/fb.h> better not rely on kernel headers in userspace ...
 
 #define FBIOBLANK             OD_IO( 'F', 0x11 ) // 0x4611
 
 /* VESA Blanking Levels */
 #define VESA_NO_BLANKING      0
 #define VESA_VSYNC_SUSPEND    1
 #define VESA_HSYNC_SUSPEND    2
 #define VESA_POWERDOWN        3
 
-
+/**
+ * This sets the display on or off
+ */
 bool ODevice::setDisplayStatus ( bool on )
 {
         if ( d-> m_model == Model_Unknown )
                 return false;
 
         bool res = false;
         int fd;
 
         if (( fd = ::open ( "/dev/fb0", O_RDWR )) >= 0 ) {
                 res = ( ::ioctl ( fd, FBIOBLANK, on ? VESA_NO_BLANKING : VESA_POWERDOWN ) == 0 );
                 ::close ( fd );
         }
         return res;
 }
 
-bool ODevice::setDisplayBrightness ( int )
+/**
+ * This sets the display brightness
+ * @return success or failure
+ */
+bool ODevice::setDisplayBrightness ( int p)
 {
+        Q_UNUSED( p )
         return false;
 }
 
 int ODevice::displayBrightnessResolution ( ) const
 {
         return 16;
 }
 
+/**
+ * This returns the vendor as string
+ * @return Vendor as QString
+ */
 QString ODevice::vendorString ( ) const
 {
         return d-> m_vendorstr;
 }
 
+/**
+ * This returns the vendor as one of the values of OVendor
+ * @return OVendor
+ */
 OVendor ODevice::vendor ( ) const
 {
         return d-> m_vendor;
 }
 
+/**
+ * This returns the model as a string
+ * @return A string representing the model
+ */
 QString ODevice::modelString ( ) const
 {
         return d-> m_modelstr;
 }
 
+/**
+ * This does return the OModel used
+ */
 OModel ODevice::model ( ) const
 {
         return d-> m_model;
 }
 
+/**
+ * This does return the systen name
+ */
 QString ODevice::systemString ( ) const
 {
         return d-> m_systemstr;
 }
 
+/**
+ * Return System as OSystem value
+ */
 OSystem ODevice::system ( ) const
 {
         return d-> m_system;
 }
 
+/**
+ * @return the version string of the base system
+ */
 QString ODevice::systemVersionString ( ) const
 {
         return d-> m_sysverstr;
 }
 
+/**
+ *  @return the current Transformation
+ */
 Transformation ODevice::rotation ( ) const
 {
         return d-> m_rotation;
 }
 
+/**
+ * This plays an alarmSound
+ */
 void ODevice::alarmSound ( )
 {
 #ifndef QT_NO_SOUND
         static Sound snd ( "alarm" );
 
         if ( snd. isFinished ( ))
                 snd. play ( );
 #endif
 }
 
+/**
+ * This plays a key sound
+ */
 void ODevice::keySound ( )
 {
 #ifndef QT_NO_SOUND
         static Sound snd ( "keysound" );
 
         if ( snd. isFinished ( ))
                 snd. play ( );
 #endif
 }
 
+/**
+ * This plays a touch sound
+ */
 void ODevice::touchSound ( )
 {
 
 #ifndef QT_NO_SOUND
         static Sound snd ( "touchsound" );
 
         if ( snd. isFinished ( ))
                 snd. play ( );
 #endif
 }
 
-
+/**
+ * This method will return a list of leds
+ * available on this device
+ * @return a list of LEDs.
+ */
 QValueList <OLed> ODevice::ledList ( ) const
 {
         return QValueList <OLed> ( );
 }
 
+/**
+ * This does return the state of the LEDs
+ */
 QValueList <OLedState> ODevice::ledStateList ( OLed /*which*/ ) const
 {
         return QValueList <OLedState> ( );
 }
 
+/**
+ * @return the state for a given OLed
+ */
 OLedState ODevice::ledState ( OLed /*which*/ ) const
 {
         return Led_Off;
 }
 
-bool ODevice::setLedState ( OLed /*which*/, OLedState /*st*/ )
+/**
+ * Set the state for a LED
+ * @param which Which OLed to use
+ * @param st The state to set
+ * @return success or failure
+ */
+bool ODevice::setLedState ( OLed which, OLedState st )
 {
+        Q_UNUSED( which )
+        Q_UNUSED( st    )
         return false;
 }
 
+/**
+ * @return if the device has a light sensor
+ */
 bool ODevice::hasLightSensor ( ) const
 {
         return false;
 }
 
+/**
+ * @return a value from the light senso
+ */
 int ODevice::readLightSensor ( )
 {
         return -1;
 }
 
+/**
+ * @return the light sensor resolution whatever that is ;)
+ */
 int ODevice::lightSensorResolution ( ) const
 {
         return 0;
 }
 
+/**
+ * @return a list of hardware buttons
+ */
 const QValueList <ODeviceButton> &ODevice::buttons ( )
 {
         initButtons ( );
 
         return *d-> m_buttons;
 }
 
+/**
+ * @return The amount of time that would count as a hold
+ */
 uint ODevice::buttonHoldTime ( ) const
 {
         return d-> m_holdtime;
 }
 
+/**
+ * This method return a ODeviceButton for a key code
+ * or 0 if no special hardware button is available for the device
+ *
+ * @return The devicebutton or 0l
+ * @see ODeviceButton
+ */
 const ODeviceButton *ODevice::buttonForKeycode ( ushort code )
 {
         initButtons ( );
 
         for ( QValueListConstIterator<ODeviceButton> it = d-> m_buttons-> begin ( ); it != d-> m_buttons-> end ( ); ++it ) {
                 if ( (*it). keycode ( ) == code )
                         return &(*it);
         }
         return 0;
 }
 
 void ODevice::reloadButtonMapping ( )
 {
         initButtons ( );
 
         Config cfg ( "ButtonSettings" );