Add more documentation to lcd_lib, lcterm and pylcd driver

Refactor todo entries in the documentation and add them to the TODO file
Document some known bugs and remove some that are known to be fixed.

BUGS

@@ -1,21 +1,22 @@
 Known Bugs:
 --------------
 
-V0.4.3:
+V0.5dev:
+  - A client gets disconnected if it sends a many commands quickly. This can
+    happen during initial screen setup or if vBars are used on large (40x4)
+    displays.
+  - If vBars are used together with ICON_BLOCK_FILLED on the same screen and
+    that icon is implemented as a custom char, it sometimes is replaced with
+    a non full block from the vBar.
+
+
+Bugs in previous versions (not checked if the still exist):
+-----------------------------------------------------------
+    
    - A client may cause the connection to LCDd to break or even crash
      LCDd by not reading the replies from LCDd
          See one of the example clients (clients/examples) for details.
    - MtxOrb driver
        - "lcdproc K" does not display properly in between digit.
-
-V0.4-pre1:
    - The server tends to crash if the joystick driver is the last one loaded.
      Specifically, if the "E" key is pressed...
-   - The lcdproc client doesn't have a disk screen.
-   - Menus are not implemented.
-   - Scrollers are not implemented.
-   - Dynamic driver adding/removing is not implemented.
-   - LCDproc needs more documentation!
-
-But, it's pretty stable considering I rewrote 400k of source since the
-last release...

TODO

@@ -6,9 +6,14 @@ Please send a message to the mailing list if you have any question.
 
 Things for the short term:
 - Use centralized command message parsing engine (more secure)
-- more features for existing display drivers
-  (e.g. adapt them to bignum library)
+- more features for existing display drivers (e.g. adapt them to bignum library)
 - documentation (any help is appreciated)
+- lcd_lib: Make use of the options parameter to specify SEAMLESS_HBARS, the
+  height of hbars, etc.
+- lcterm: Support keyboard input
+- MtxOrb: Recover the code for I2C connectivity to MtxOrb
+- shuttleVFD: Use output() method for these special "out-of-band" symbols.
+
 
 Things for the longer term:
 

server/drivers/lcd_lib.c

@@ -1,3 +1,13 @@
+/** \file server/drivers/lcd_lib.c
+ * LCD library of useful functions for drivers.
+ *
+ * Drawn from the "base driver" which really was the precursor
+ * to this library.
+ *
+ * \todo Make use of the \c options parameter to specify SEAMLESS_HBARS,
+ *       the height of hbars, etc.
+ */
+
 #include <stdlib.h>
 #include <unistd.h>
 #include <string.h>
@@ -8,26 +18,16 @@
 # include "config.h"
 #endif
 
-
-// ==================================================
-// LCD library of useful functions for drivers
-// ==================================================
-
-// Drawn from the "base driver" which really was the precursor
-// to this library....
-
-// TODO: What should this really be?  Probably should be in the
-// driver code or headers or something...
-
-void
-lib_hbar_static (Driver *drvthis, int x, int y, int len, int promille, int options, int cellwidth, int cc_offset)
-/*
+/**
  * This function places a hbar using the v0.5 API format and the given cellwidth.
  * It assumes that custom chars have been statically defined, so that number
- * 1 has 1 pixel, number 2 has 2 etc...
+ * 1 has 1 pixel, number 2 has 2 etc.
+ * 
  * LCDs that have the custom chars at other char numbers than 0 should put the
  * first custom char number in cc_offset.
  */
+void
+lib_hbar_static (Driver *drvthis, int x, int y, int len, int promille, int options, int cellwidth, int cc_offset)
 {
 	int total_pixels  = ((long) 2 * len * cellwidth + 1 ) * promille / 2000;
 	int pos;
@@ -55,16 +55,16 @@ lib_hbar_static (Driver *drvthis, int x, int y, int len, int promille, int optio
 	}
 }
 
-
-void
-lib_vbar_static (Driver *drvthis, int x, int y, int len, int promille, int options, int cellheight, int cc_offset)
-/*
+/**
  * This function places a vbar using the v0.5 API format and the given cellwidth.
  * It assumes that custom chars have been statically defined, so that number
- * 1 has 1 pixel, number 2 has 2 etc., just like in good old times...
+ * 1 has 1 pixel, number 2 has 2 etc., just like in good old times.
+ * 
  * LCDs that have the custom chars at other char numbers than 0 should put the
  * first custom char number in cc_offset.
  */
+void
+lib_vbar_static (Driver *drvthis, int x, int y, int len, int promille, int options, int cellheight, int cc_offset)
 {
 	int total_pixels = ((long) 2 * len * cellheight + 1 ) * promille / 2000;
 	int pos;

server/drivers/lcterm.c

@@ -1,6 +1,10 @@
 /** \file server/drivers/lcterm.c
  * LCDd \c lcterm driver for the LCTerm serial LCD terminal from Helmut Neumark Elektronik,
  * www.neumark.de.
+ *
+ * \todo Support keyboard input
+ * \todo Convert to use pixel-row based logic for custom characters, icons,
+ *       bar graphs etc.
  */
 
 /*
@@ -23,8 +27,6 @@
   This driver is mostly based on the HD44780 and the LCDM001 driver.
   (Hopefully I have NOT forgotten any file I have stolen code from.
   If so send me an e-mail or add your copyright here!)
-
-  TODO: support keyboard input
 */
 
 #include <stdlib.h>
@@ -170,7 +172,7 @@ lcterm_init (Driver *drvthis)
 
   report(RPT_DEBUG, "%s: init() done", drvthis->name);
 
-  return 1;
+  return 0;
 }
 
 
@@ -327,8 +329,6 @@ lcterm_string (Driver *drvthis, int x, int y, const char string[])
  * \param n        Custom character to define [0 - (NUM_CCs-1)].
  * \param dat      Array of 40(=8*5=cellheight*cellwidth) bytes, each representing a pixel
  *                 starting from the top left to the bottom right.
- * \todo
- * Convert \c dat to use one byte per pixel-row as e.g. in the \c CFontzPackage driver.
  */
 MODULE_EXPORT void
 lcterm_set_char (Driver *drvthis, int n, char *dat)
@@ -358,8 +358,7 @@ lcterm_set_char (Driver *drvthis, int n, char *dat)
 
 /**
  * Set up vertical bars.
- * \todo
- * Get rid of it by using pixel-row based logic as e.g. in the \c CFontzPackage driver.
+ * \param drvthis  Pointer to driver structure.
  */
 static void
 lcterm_init_vbar (Driver *drvthis)
@@ -461,8 +460,7 @@ lcterm_init_vbar (Driver *drvthis)
 
 /**
  * Set up horizontal bars.
- * \todo
- * Get rid of it by using pixel-row based logic as e.g. in the \c CFontzPackage driver.
+ * \param drvthis  Pointer to driver structure.
  */
 static void
 lcterm_init_hbar (Driver *drvthis)
@@ -574,9 +572,10 @@ lcterm_hbar(Driver *drvthis, int x, int y, int len, int promille, int options)
 }
 
 
-/////////////////////////////////////////////////////////////////
-// Sets up for big numbers.
-//
+/**
+ * Sets up for big numbers.
+ * \param drvthis  Pointer to driver structure.
+ */
 static void
 lcterm_init_num (Driver *drvthis)
 {
@@ -681,9 +680,6 @@ lcterm_init_num (Driver *drvthis)
  * \param drvthis  Pointer to driver structure.
  * \param x        Horizontal character position (column).
  * \param num      Character to write (0 - 10 with 10 representing ':')
- *
- * \todo
- * Convert to pixel-row based logic to be able to use the adv_bignum library.
  */
 MODULE_EXPORT void
 lcterm_num (Driver *drvthis, int x, int num)
@@ -789,9 +785,6 @@ lcterm_num (Driver *drvthis, int x, int num)
  * \param icon     synbolic value representing the icon.
  * \retval 0       Icon has been successfully defined/written.
  * \retval <0      Server core shall define/write the icon.
- *
- * \todo
- * Convert to using pixel-row based logic as e.g. in the \c CFontzPackage driver.
  */
 MODULE_EXPORT int
 lcterm_icon (Driver *drvthis, int x, int y, int icon)

server/drivers/pylcd.c

@@ -7,6 +7,9 @@
  *
  * Contact Thomas Riewe <thomas.riewe@pyramid.de> for further
  * information on the LCD.
+ *
+ * \todo Convert to use pixel-row based logic for custom characters, icons,
+ *       bar graphs etc.
  */
 
 /*
@@ -557,8 +560,6 @@ pyramid_chr (Driver *drvthis, int x, int y, char c)
  * \param n        Custom character to define [0 - (NUM_CCs-1)].
  * \param dat      Array of 40(=8*5=cellheight*cellwidth) bytes, each representing a pixel
  *                 starting from the top left to the bottom right.
- * \todo
- * Convert \c dat to use one byte per pixel-row as e.g. in the \c CFontzPackage driver.
  */
 MODULE_EXPORT void pyramid_set_char (Driver *drvthis, int n, char *dat)
 {
@@ -635,8 +636,7 @@ MODULE_EXPORT int  pyramid_cellheight (Driver *drvthis)
 
 /**
  * Set up vertical bars.
- * \todo
- * Get rid of it by using pixel-row based logic as e.g. in the \c CFontzPackage driver.
+ * \param drvthis  Pointer to driver structure.
  */
 static void
 pyramid_init_vbar (Driver *drvthis)
@@ -728,8 +728,7 @@ pyramid_init_vbar (Driver *drvthis)
 
 /**
  * Set up horizontal bars.
- * \todo
- * Get rid of it by using pixel-row based logic as e.g. in the \c CFontzPackage driver.
+ * \param drvthis  Pointer to driver structure.
  */
 static void
 pyramid_init_hbar (Driver *drvthis)
@@ -796,6 +795,11 @@ pyramid_init_hbar (Driver *drvthis)
 	}
 }
 
+/**
+ * Defines some custom characters.
+ * These characters are enabled if the value 0x100 is sent to the \c output command.
+ * \param drvthis  Pointer to driver structure.
+ */
 static void
 pyramid_init_custom1 (Driver *drvthis)
 {