Updated files mainly because of the translation stuff and

doxygen conform comments.

include/sane/sanei.h

@@ -15,9 +15,49 @@
    You should have received a copy of the GNU General Public License
    along with sane; see the file COPYING.  If not, write to the Free
    Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+*/
 
-   This file declares SANE internal routines that are provided to
+/** @file sanei.h
-   simplify backend implementation.  */
+ *  This file declares SANE internal routines that are provided to
+ *  simplify backend implementation. 
+ */
+
+/* Doxygen documentation */
+
+/** @mainpage SANEI (SANE internal routines) documentation
+ *
+ * @section intro Introduction
+ *
+ * The header files in the include/sane/ directory named sanei_*.h provide
+ * function declarations and macros that can be used by every SANE backend.
+ * Their implementations can be found in the sanei/ directory. The code aims
+ * to be platform-independent to avoid lots of #ifdef code in the backends.
+ * Please use the SANEI functions wherever possible.
+ *
+ * This documentation was created by the use of doxygen, the 
+ * doc/doxygen-sanei.conf configuration file and dcoumentation in the sanei_*.h
+ * files.
+ *
+ * This documenation is far from complete. Any help is appreciated.
+ *
+ * @section additional Additional documentation
+ * - The SANE standard can be found at <a 
+ *   href="http://www.mostang.com/sane/html/">the SANE webserver</a>.
+ * - Information on how to write a backend: <a
+ *   href="../backend-writing.txt">backend-writing.txt</a>.
+ * - General SANE documentation is on <a
+ *   href="http://www.mostang.com/sane/docs.html>the SANE documentation
+ *   page</a>.
+ * 
+ * @section contact Contact 
+ *
+ * The common way to contact the developers of SANE is the sane-devel
+ * mailing list. See the <a
+ * href="http://www.mostang.com/sane/mail.html">mailing list webpage</a>
+ * for details. That's the place to ask questions, report bugs, or announce
+ * a new backend.
+ * 
+ */
 
 #ifndef sanei_h
 #define sanei_h
@@ -26,14 +66,41 @@
 
 /* A few convenience macros:  */
 
+/** @def STRINGIFY(x)
+ * Turn parameter into string.
+ *
+ */
 #define STRINGIFY1(x)	#x
 #define STRINGIFY(x)	STRINGIFY1(x)
 
+/** @def PASTE(x,y)
+ * Concatenate parameters.
+ *
+ */
 #define PASTE1(x,y)	x##y
 #define PASTE(x,y)	PASTE1(x,y)
 
+/** @def NELEMS(a)
+ * Return number of elements of an array.
+ *
+ */
 #define NELEMS(a)	((int)(sizeof (a) / sizeof (a[0])))
 
+/**
+ * Check the constraints of a SANE option and adjust its value if necessary.
+ *
+ * Depending on the type of the option and constraint, value is modified
+ * to fit inside constraint.
+ *
+ * @param opt   option to check
+ * @param value value of the option
+ * @param info  info is set to SANE_INFO_INEXACT if value was changed
+ *
+ * @return 
+ * - SANE_STATUS_GOOD     - on success
+ * - SANE_STATUS_INVAL    - if the function wasn't able to fit value into the
+ *   constraint or any other error occured
+ */
 extern SANE_Status sanei_constrain_value (const SANE_Option_Descriptor * opt,
 					  void * value, SANE_Word * info);
 extern int sanei_save_values (int fd, SANE_Handle device);

include/sane/sanei_ab306.h

@@ -37,6 +37,23 @@
    If you write modifications of your own for SANE, it is your choice
    whether to permit this exception to apply to your modifications.
    If you do not wish that, delete this exception notice.  */
+
+
+/** @file sanei_ab306.h
+ * Support for the Mustek-proprietary SCSI-over-parallel-port
+ * interface AB306.
+ *
+ * This chip is used by the Mustek Paragon 600 II N. It's similar to a parport
+ * but has it's own ISA card and cable. 
+ * 
+ * /dev/port access is used where available. If this doesn't work, inb/outb
+ * functions or inb/outb assembler code is used.
+ *
+ * Depending on the operating system it may be necessary to run this code as
+ * root.
+ */
+
+
 #ifndef sanei_ab306_h
 #define sanei_ab306_h
 
@@ -44,14 +61,95 @@
 
 #include <sane/sane.h>
 
+/**
+ * Open the connection to an AB306 device.
+ *
+ * The scanner is also turned on.
+ *
+ * @param dev Port address as text.
+ * @param fd  Information about port address and I/O method. fd is not a file
+ *            descriptor. The name and type are used for compatibility reasons.
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_INVAL - if the port address can't be interpreted
+ * - SANE_STATUS_IO_ERROR - if the device file for a port couldn't be accessed
+ */
 SANE_Status	sanei_ab306_open (const char *dev, int *fd);
+
+/**
+ * Close the connection to an AB306 device.
+ *
+ * @param fd  Information about port address and I/O method.
+ *
+ */
 void		sanei_ab306_close (int fd);
+
+/**
+ * Exit ab306.
+ *
+ * Also powers down all devices.
+ *
+ */
 void		sanei_ab306_exit (void);
 
+/**
+ * Get the permission for direct access to the ports.
+ *
+ * The only occasion this function must be called, is when the I/O privilege
+ * was lost, e.g. after forking. Otherwise, it's called automatically by
+ * sanei_ab306_open().
+ *
+ * @param fd  Information about port address and I/O method.
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_IO_ERROR - if the i/o privilege was denied by the operating
+ *   system
+ */
 SANE_Status	sanei_ab306_get_io_privilege (int fd);
+/**
+ * Find out if the device is ready to accept new commands.
+ *
+ * @param fd  Information about port address and I/O method.
+ *
+ * @return
+ * - SANE_STATUS_GOOD - if the device is ready
+ * - SANE_STATUS_DEVICE_BUSY if the device is still busy (try again later)
+ */
 SANE_Status	sanei_ab306_test_ready (int fd);
+
+/**
+ * Send a command to the AB306 device.
+ *
+ * @param fd  Information about port address and I/O method.
+ * @param src Data to be sent to the device.
+ * @param src_size Size of data to be sent to the device.
+ * @param dst Data to be received from the device.
+ * @param dst_size Size of data to be received from the device
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_IO_ERROR - if an error occured during the dialog with the
+ *   device
+ */
 SANE_Status	sanei_ab306_cmd (int fd, const void *src, size_t src_size,
 				 void *dst, size_t *dst_size);
+
+/**
+ * Read scanned image data.
+ *
+ * @param fd  Information about port address and I/O method.
+ * @param planes Bytes per pixel (3 for color, 1 for all other modes)
+ * @param buf Buffer for image data.
+ * @param lines Number of lines
+ * @param bpl Bytes per line
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_IO_ERROR - if an error occured during the dialog with the 
+ *   device
+ */
 SANE_Status	sanei_ab306_rdata (int fd, int planes,
 				   SANE_Byte *buf, int lines, int bpl);
 

include/sane/sanei_lm983x.h

@@ -41,9 +41,13 @@
    whether to permit this exception to apply to your modifications.
    If you do not wish that, delete this exception notice.
 
-   Interface files for the LM9831/2/3 chip,
+*/
-   a chip used in many USB scanners.
 
+/** @file sanei_lm983x.h
+ *  Interface files for the NS LM9831/2/3 USB chip.
+ *
+ *  The National Semiconductor LM9831, LM9832, and LM9833 chips are used in
+ *  many USB scanners. Examples include Plustek and Mustek devices.
  */
 
 #ifndef sanei_lm983x_h
@@ -52,22 +56,92 @@
 #include "../include/sane/config.h"
 #include "../include/sane/sane.h"
 
+/**
+ * Read one data byte from a specific LM983x register.
+ *
+ * @param fd    - device file descriptor (SANE_Int)
+ * @param reg   - number of register (SANE_Byte)
+ * @param value - byte value to be written (SANE_Byte *)
+ *
+ * @return The SANE status code for the operation (SANE_Status):
+ * - SANE_STATUS_GOOD     - on success
+ * - SANE_STATUS_IO_ERROR - system write function failed
+ * - SANE_STATUS_INVAL    - register out of range
+ */
 #define sanei_lm983x_read_byte(fd, reg, value) \
           sanei_lm983x_read (fd, reg, value, 1, 0)
 
+/**
+ * Initialize sanei_lm983x.
+ *
+ * Currently, this function only enables the debugging functionality.
+ */
 extern void sanei_lm983x_init( void );
 
+/**
+ * Write one data byte to a specific LM983x register.
+ *
+ * @param fd    - device file descriptor
+ * @param reg   - number of register
+ * @param value - byte value to be written
+ *
+ * @return
+ * - SANE_STATUS_GOOD     - on success
+ * - SANE_STATUS_IO_ERROR - system write function failed
+ * - SANE_STATUS_INVAL    - register out of range
+ */
 extern SANE_Status sanei_lm983x_write_byte( SANE_Int fd,
                                             SANE_Byte reg, SANE_Byte value );
 
+/**
+ * Write one or more data bytes to one or more specific LM983x
+ * registers.
+ *
+ * @param fd        - device file descriptor
+ * @param reg       - number of start-register
+ * @param buffer    - buffer to be written
+ * @param len       - number of bytes to be written
+ * @param increment - SANE_TRUE enables the autoincrement of the register
+ *                    value during the write cycle, SANE_FALSE disables this
+ *
+ * @return
+ * - SANE_STATUS_GOOD     - on success
+ * - SANE_STATUS_IO_ERROR - system read function failed
+ * - SANE_STATUS_INVAL    - register out of range or len field was 0
+ */
 extern SANE_Status sanei_lm983x_write( SANE_Int fd, SANE_Byte reg,
                                        SANE_Byte *buffer, SANE_Word len,
                                                          SANE_Bool increment );
 
+/**
+ * Read one or more data bytes from one ore more specific LM983x
+ * registers.
+ *
+ * @param fd        - device file descriptor
+ * @param reg       - number of start-register
+ * @param buffer    - buffer to receive the data
+ * @param len       - number of bytes to receive
+ * @param increment - SANE_TRUE enables the autoincrement of the register
+ *                    value during the read cylce, SANE_FALSE disables this
+ *
+ * @return
+ * - SANE_STATUS_GOOD     - on success
+ * - SANE_STATUS_IO_ERROR - system read function failed
+ * - SANE_STATUS_INVAL    - register out of range
+ * - SANE_STATUS_EOF      - if nothing can't be read
+ */
 extern SANE_Status sanei_lm983x_read( SANE_Int fd, SANE_Byte reg,
                                       SANE_Byte *buffer, SANE_Word len,
                                                          SANE_Bool increment );
 
+/**
+ * Reset the LM983x chip.
+ *
+ * @param fd    - device file descriptor
+ * @return 
+ * - SANE_TRUE  - reset successfuly done
+ * - SANE_FALSE - reset failed
+ */
 extern SANE_Bool sanei_lm983x_reset( SANE_Int fd );
 					    					
 #endif /* sanei_lm983x_h */