From 82c69e7a6ee56da6398aa427a0426b69ee80e3ff Mon Sep 17 00:00:00 2001
From: mmdolze <mmdolze@users.sourceforge.net>
Date: Sat, 28 Feb 2009 07:43:54 +0000
Subject: [PATCH] Add proper doxygen to uPause Decide on one style of comments

---
 server/drivers/hd44780-lcd2usb.c | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)

diff --git a/server/drivers/hd44780-lcd2usb.c b/server/drivers/hd44780-lcd2usb.c
index 871c772..49713a8 100644
--- a/server/drivers/hd44780-lcd2usb.c
+++ b/server/drivers/hd44780-lcd2usb.c
@@ -25,14 +25,24 @@
 #endif
 
 
-// connection type specific functions to be exposed using pointers in init()
+/* connection type specific functions to be exposed using pointers in init() */
 void lcd2usb_HD44780_senddata(PrivateData *p, unsigned char displayID, unsigned char flags, unsigned char ch);
 void lcd2usb_HD44780_backlight(PrivateData *p, unsigned char state);
 unsigned char lcd2usb_HD44780_scankeypad(PrivateData *p);
 void lcd2usb_HD44780_close(PrivateData *p);
 void lcd2usb_HD44780_set_contrast(PrivateData *p, unsigned char value);
-// Pseudo uPause function. A lcd2usb device takes care of timing itself.
-void lcd2usb_HD44780_uPause(PrivateData *p, int usecs) {}
+
+
+/**
+ * Pseudo (empty) uPause function.
+ * Override the uPause function as a lcd2usb device takes care of timing itself.
+ * \param p      Pointer to PrivateData structure (unused)
+ * \param usecs  Number of micro-seconds to sleep (ignored)
+ */
+void
+lcd2usb_HD44780_uPause(PrivateData *p, int usecs)
+{
+}
 
 
 /**
@@ -100,8 +110,9 @@ hd_init_lcd2usb(Driver *drvthis)
 
   common_init(p, IF_4BIT);
 
-  // Replace uPause with empty one after initialization
+  /* replace uPause with empty one after initialization */
   p->hd44780_functions->uPause = lcd2usb_HD44780_uPause;
+
   return 0;
 }
 
@@ -126,18 +137,20 @@ lcd2usb_HD44780_senddata(PrivateData *p, unsigned char displayID, unsigned char
 
 /**
  * Turn display backlight on or off.
+ * Backlight is turned on or off by toggeling between the brightness and
+ * offbrightness values.
  * \param p      Pointer to driver's private data structure.
  * \param state  New backlight status.
  */
 void
 lcd2usb_HD44780_backlight(PrivateData *p, unsigned char state)
 {
-  // Get backlight brightness.
+  /* get backlight brightness */
   int promille = (state == BACKLIGHT_ON) ? p->brightness : p->offbrightness;
   
   p->hd44780_functions->drv_report(RPT_INFO, "lcd2usb_HD44780_backlight: Setting backlight to %d", promille);
 
-  // And set it (converted from [0,1000] -> [0,255]).
+  /* and set it (converted from [0,1000] -> [0,255]) */
   if (usb_control_msg(p->usbHandle, USB_TYPE_VENDOR, LCD2USB_SET_BRIGHTNESS,
                    (promille * 255) / 1000, 0, NULL, 0, 1000) < 0)
     p->hd44780_functions->drv_report(RPT_WARNING, "lcd2usb_HD44780_backlight: setting backlight failed");
@@ -171,7 +184,7 @@ lcd2usb_set_brightness(Driver *drvthis, int state, int promille)
 {
   PrivateData *p = drvthis->private_data;
 
-  // Check if value within range
+  /* check if value within range */
   if (promille < 0 || promille > 1000)
     return;
 
@@ -186,7 +199,7 @@ lcd2usb_set_brightness(Driver *drvthis, int state, int promille)
 /**
  * Read keypress.
  * \param p  Pointer to driver's private data structure.
- * \return   Bitmap of the pressed keys.
+ * \return   Scancode of the key as returned by the lcd2usb device.
  */
 unsigned char
 lcd2usb_HD44780_scankeypad(PrivateData *p)