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.
2009-03-22 11:11:18 +00:00
parent 92185c9ea0
commit 15f2bf4ba3
5 changed files with 61 additions and 58 deletions
@@ -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;
@@ -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)
@@ -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)
 {