Added/adjusted documentation for doxygen.

Henning Meier-Geinitz <henning@meier-geinitz.de>

include/sane/sanei_pa4s2.h

@@ -37,8 +37,13 @@
    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. 
+*/
 
-   This file implements an interface for the Mustek PP chipset A4S2 */
+/** @file sanei_pa4s2.h
+ * This file implements an interface for the Mustek PP chipset A4S2 
+ *
+ * @sa sanei_usb.h, sanei_ab306.h, sanei_lm983x.h, sanei_scsi.h, sanei_pio.h
+ */
 
 #ifndef sanei_pa4s2_h
 #define sanei_pa4s2_h
@@ -46,46 +51,119 @@
 #include <sys/types.h>
 #include <sane/sane.h>
 
-/* options to controll interface operations */
+/** @name Options to control interface operations */
+/* @{ */
 #define SANEI_PA4S2_OPT_DEFAULT		0	/* normal mode */
 #define SANEI_PA4S2_OPT_TRY_MODE_UNI	1	/* enable UNI protocoll */
 #define SANEI_PA4S2_OPT_ALT_LOCK	2	/* use alternative lock cmd */
+/* @} */
 
-/* 
+/** Open pa4s2 device 
-   opens *dev as pa4s2 device, possible values for *dev are "0x378",
+ *
-   "0x278" and "0x3BC"
+ * Opens *dev as pa4s2 device.
+ *
+ * @param dev IO port address ("0x378", "0x278", or "0x3BC")
+ * @param fd file descriptor
+ * 
+ * @return 
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_INVAL - if no scanner was found or the port number was wrong
+ * - SANE_STATUS_DEVICE_BUSY - if the device is already in use
+ * - SANE_STATUS_IO_ERROR - if the port couldn't be accessed
+ * 
  */
 extern SANE_Status sanei_pa4s2_open (const char *dev, int *fd);
 
-/* closes the device */
+/** Close pa4s2 device 
+ *
+ * @param fd file descriptor
+ */
 extern void sanei_pa4s2_close (int fd);
 
-/* 
+/** Set/get options
-   sets/gets interface options. Options will be taken over, when set is
+ *
-   SANE_TRUE. These options should be set before the firt device is opened
+ * Sets/gets interface options. Options will be taken over, when set is
+ * SANE_TRUE. These options should be set before the first device is opened
+ *
+ * @param options pointer to options
+ * @param set set (SANE_TRUE) or get (SANE_FALSE) options
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
  */
 extern SANE_Status sanei_pa4s2_options (u_int * options, int set);
 
-/*
+/** Enables/disable device
-   enables/disables the device. possible values for enable are SANE_TRUE
+ *
-   and SANE_FALSE. When the device is disabled, the printer can accessed,
+ * When the device is disabled, the printer can be accessed, when it's enabled
-   when it's enabled data can be read/written 
+ * data can be read/written.
+ *
+ * @param fd file descriptor
+ * @param enable enable (SANE_TRUE) or disable (SANE_FALSE) device
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_INVAL - if fd is invalid or device not in use
  */
 extern SANE_Status sanei_pa4s2_enable (int fd, int enable);
 
-/*
+/** Select a register
-   the function to read a register is split up in three parts, so a register
+ *
-   can be read more than once
+ * The function to read a register is split up in three parts, so a register
+ * can be read more than once.
+ *
+ * @param fd file descriptor
+ * @param reg register
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_INVAL - if fd is invalid or device not in use
+ *
+ * @sa sanei_pa4s2_readbyte(), sanei_pa4s2_readend()
  */
-
-/* selects a register */
 extern SANE_Status sanei_pa4s2_readbegin (int fd, u_char reg);
-/* reads a register */
+
+
+/** Read a register 
+ *
+ * The function to read a register is split up in three parts, so a register
+ * can be read more than once.
+ *
+ * @param fd file descriptor
+ * @param val pointer to value
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_INVAL - if fd is invalid or device not in use
+ *
+ * @sa sanei_pa4s2_readbegin(), sanei_pa4s2_readend()
+ */
 extern SANE_Status sanei_pa4s2_readbyte (int fd, u_char * val);
-/* terminates reading sequence */
+
+/** Terminate reading sequence 
+ *
+ * The function to read a register is split up in three parts, so a register
+ * can be read more than once.
+ *
+ * @param fd file descriptor
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_INVAL - if fd is invalid or device not in use
+ * @sa sanei_pa4s2_readbegin(), sanei_pa4s2_readbyte()
+ */
 extern SANE_Status sanei_pa4s2_readend (int fd);
 
-/* reads a register */
+/** Write a register
+ *
+ * @param fd file descriptor
+ * @param reg register
+ * @param val value to be written
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_INVAL - if fd is invalid or device not in use
+ */
 extern SANE_Status sanei_pa4s2_writebyte (int fd, u_char reg, u_char val);
 
 

include/sane/sanei_scsi.h

@@ -16,7 +16,13 @@
    along with sane; see the file COPYING.  If not, write to the Free
    Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
-   Generic interface to SCSI drivers.  */
+*/
+
+/** @file sanei_scsi.h
+ *  Generic interface to SCSI drivers.  
+ *  @sa sanei_usb.h, sanei_ab306.h,sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h,
+ *  and man sane-scsi(5) for user-oriented documentation
+ */
 
 #ifndef sanei_scsi_h
 #define sanei_scsi_h
@@ -25,94 +31,181 @@
 
 #include <sane/sane.h>
 
+/** Sense handler
+ *
+ * The sense handler can be implemented in backends. It's for deciding
+ * which sense codes should be considered an error and which shouldn't.
+ *
+ * @param fd file descriptor
+ * @param sense_buffer pointer to buffer containing sense codes
+ * @param arg pointer to data buffer
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success (sense isn't regarded as error)
+ * - any other status if sense code is regarded as error
+ */
 typedef SANE_Status (*SANEI_SCSI_Sense_Handler) (int fd,
 						 u_char *sense_buffer,
 						 void *arg);
-
+/** Maximum size of a SCSI request
+ */
 extern int sanei_scsi_max_request_size;
 
-/* Find each SCSI devices that matches the pattern specified by the
+/** Find SCSI devices.
-   arguments.  String arguments can be "omitted" by passing NULL,
+ *
-   integer arguments can be "omitted" by passing -1.  Callback ATTACH
+ * Find each SCSI device that matches the pattern specified by the
-   gets invoked once for each device.  The DEV argument passed to this
+ * arguments.  String arguments can be "omitted" by passing NULL,
-   callback is the real devicename.
+ * integer arguments can be "omitted" by passing -1.  
-
+ * 
-   Example: vendor="HP" model=NULL, type=NULL, bus=3, id=-1, lun=-1 would
+ *   Example: vendor="HP" model=NULL, type=NULL, bus=3, id=-1, lun=-1 would
-	    attach all HP devices on SCSI bus 3.  */
+ *	    attach all HP devices on SCSI bus 3.
+ *
+ * @param vendor
+ * @param model
+ * @param type
+ * @param bus
+ * @param channel
+ * @param id
+ * @param lun
+ * @param attach callback invoked once for each device
+ * @param dev real devicename (passed to attach callback)
+ *
+ */
 extern void sanei_scsi_find_devices (const char *vendor, const char *model,
 				     const char *type,
 				     int bus, int channel, int id, int lun,
 				     SANE_Status (*attach) (const char *dev));
 
+
+/** Open a SCSI device
+ *
+ * Opens a SCSI device by its device filename and returns a file descriptor.
+ * If it's necessary to adjust the SCSI buffer size, use 
+ * sanei_scsi_open_extended().
+ *
+ * @param devicename name of the devicefile, e.g. "/dev/sg0"
+ * @param fd file descriptor
+ * @param sense_handler called whenever the SCSI driver returns a sense buffer
+ * @param sense_arg pointer to data for the sense handler
+ * 
+ * @return 
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to
+ *   permissions
+ * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
+ * - SANE_STATUS_INVAL - if the filename was invalid or an unknown error occured
+ *
+ * @sa sanei_scsi_open_extended(), HAVE_SANEI_SCSI_OPEN_EXTENDED
+ */
 extern SANE_Status sanei_scsi_open (const char * device_name, int * fd,
 				    SANEI_SCSI_Sense_Handler sense_handler,
 				    void *sense_arg);
 
-/* The extended open call allows a backend to ask for a specific
+/** Open a SCSI device and set the buffer size
-   buffer size. sanei_scsi_open tries to allocate a buffer of the
+ *
-   size given by *buffersize upon entry to this function. If
+ * The extended open call allows a backend to ask for a specific buffer
-   sanei_scsi_open_extended returns successfully, *buffersize
+ * size. sanei_scsi_open_extended() tries to allocate a buffer of the size
-   contains the available buffer size. This value may be both
+ * given by *buffersize upon entry to this function. If
-   smaller or larger than the value requested by the backend;
+ * sanei_scsi_open_extended returns successfully, *buffersize contains the
-   it can even be zero. The backend must decide, if it got enough
+ * available buffer size. This value may be both smaller or larger than the
-   buffer memory to work.
+ * value requested by the backend; it can even be zero. The backend must
-
+ * decide, if it got enough buffer memory to work.
-   Note that the value of *buffersize may differ for different
+ *
-   files.
+ * Note that the value of *buffersize may differ for different files.
+ *
+ * @param devicename name of the devicefile, e.g. "/dev/sg0"
+ * @param fd file descriptor
+ * @param sense_handler called whenever the SCSI driver returns a sense buffer
+ * @param sense_arg pointer to data for the sense handler
+ * @param buffersize size of the SCAI request buffer (in bytes)
+ * 
+ * @return 
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_ACCESS_DENIED - if the file couldn't be accessed due to
+ *   permissions
+ * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
+ * - SANE_STATUS_INVAL - if the filename was invalid or an unknown error occured
+ *
+ * @sa sanei_scsi_open(), HAVE_SANEI_SCSI_OPEN_EXTENDED
  */
 extern SANE_Status sanei_scsi_open_extended (
        const char * device_name, int * fd,
        SANEI_SCSI_Sense_Handler sense_handler,
        void *sense_arg, int *buffersize);
 
-/* Let backends decide, which open call to use:
+/** Do we have sanei_scsi_open_extended()?
-   if HAVE_SANEI_SCSI_OPEN_EXTENDED is defined, sanei_scsi_open_extended
+ *
-   may be used.
+ * Let backends decide, which open call to use: if
-   May also be used to decide, if sanei_scsi_req_flush_all or
+ * HAVE_SANEI_SCSI_OPEN_EXTENDED is defined, sanei_scsi_open_extended may be
-   sanei_scsi_req_flush_all_extended should be used.
+ * used.  May also be used to decide, if sanei_scsi_req_flush_all or
+ * sanei_scsi_req_flush_all_extended() should be used.
+ *
+ * @sa sanei_scsi_open(), sanei_scsi_open_extended()
 */
 #define HAVE_SANEI_SCSI_OPEN_EXTENDED
 
-/* One or more scsi commands can be enqueued by calling req_enter().
+/** Enqueue SCSI command
-   SRC is the pointer to the SCSI command and associated write data
+ *
-   and SRC_SIZE is the length of the command and data.  DST is a
+ * One or more scsi commands can be enqueued by calling sanei_scsi_req_enter().
-   pointer to a buffer in which data is returned (if any).  It may be
+ *
-   NULL if no data is returned by the command.  On input *DST_SIZE is
+ * NOTE: Some systems may not support multiple outstanding commands.  On such
-   the size of the buffer pointed to by DST, on exit, *DST_SIZE is set
+ * systems, sanei_scsi_req_enter() may block.  In other words, it is not proper
-   to the number of bytes returned in the buffer (which is less than
+ * to assume that enter() is a non-blocking routine.
-   or equal to the buffer size).  DST_SIZE may be NULL if no data is
+ *
-   expected.  IDP is a pointer to a void* that uniquely identifies
+ * @param fd file descriptor
-   the entered request.
+ * @param src pointer to the SCSI command and associated write data (if any)
-
+ * @param src_size length of the command and data
-   NOTE: Some systems may not support multiple outstanding commands.
+ * @param dst pointer to a buffer in which data is returned; NULL if no data is
-   On such systems, enter() may block.  In other words, it is not
+ *   returned
-   proper to assume that enter() is a non-blocking routine.  
+ * @param dst_size  on input, the size of the buffer pointed to by dst, on exit,
-
+ *   set to the number of bytes returned in the buffer (which is less than or equal
-   src points to a buffer which contains the SCSI command followed
+ *   to the buffer size; may be NULL if no data is expected
-   by data to be written to the device (if any)
+ * @param idp pointer to a void* that uniquely identifies the entered request
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
+ * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
+ * - SANE_STATUS_INVAL - if a locking or an unknown error occured
+ * @sa sanei_scsi_req_enter2()
+ *
 */
 extern SANE_Status sanei_scsi_req_enter (int fd,
 					 const void * src, size_t src_size,
 					 void * dst, size_t * dst_size,
 					 void **idp);
 
-/* Same as above, but with separate buffers for the SCSI command and
+/** Enqueue SCSI command and separated data 
-   for the data to be sent to the device.
+ *
-
+ * Same as sanei_scsi_req_enter(), but with separate buffers for the SCSI
-   With sanei_scsi_req_enter, the length of te SCSI command block must be
+ * command and for the data to be sent to the device.
-   guessed. While that works in most cases, Canon scanners for example
+ *
-   use the vendor specific commands 0xd4, 0xd5 and 0xd6. The Canon 
+ * With sanei_scsi_req_enter(), the length of te SCSI command block must be
-   scanners want to get 6 byte command blocks for these commands, 
+ * guessed. While that works in most cases, Canon scanners for example use the
-   but sanei_scsi_req_enter and sanei_scsi_cmd send 12 bytes. 
+ * vendor specific commands 0xd4, 0xd5 and 0xd6. The Canon scanners want to
-
+ * get 6 byte command blocks for these commands, but sanei_scsi_req_enter() and
-   cmd:      pointer to SCSI command
+ * sanei_scsi_cmd() send 12 bytes.
-   cmd_size: size of the command
+ *
-   src:      pointer to the buffer with data to be sent rto the scanner
+ * If dst_size and *dst_size are non-zero, a "read command" (ie, data transfer
-   src_size: size of that buffer
+ * from the device to the host) is assumed.
-   dst, dst_size, idp: see above
+ *
-   
+ * @param fd file descriptor
-   If dst_size and *dst_size are non-zero, a "read command" (ie,
+ * @param cmd pointer to SCSI command
-   data transfer from the device to the host) is assumed.
+ * @param cmd_size size of the command
+ * @param src pointer to the buffer with data to be sent to the scanner
+ * @param src_size size of src buffer
+ * @param dst pointer to a buffer in which data is returned; NULL if no data is
+ *   returned
+ * @param dst_size  on input, the size of the buffer pointed to by dst, on exit,
+ *   set to the number of bytes returned in the buffer (which is less than or equal
+ *   to the buffer size; may be NULL if no data is expected
+ * @param idp pointer to a void* that uniquely identifies the entered request
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
+ * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
+ * - SANE_STATUS_INVAL - if a locking or an unknown error occured
+ * @sa sanei_scsi_req_enter()
  */
 extern SANE_Status sanei_scsi_req_enter2 (int fd,
 					 const void * cmd, size_t cmd_size,
@@ -120,28 +213,97 @@ extern SANE_Status sanei_scsi_req_enter2 (int fd,
 					 void * dst, size_t * dst_size,
 					 void **idp);
 
-/* Wait for the completion of the SCSI command with id ID.  */
+/** Wait for SCSI command
+ *
+ * Wait for the completion of the SCSI command with id ID.  
+ *
+ * @param id id used in sanei_scsi_req_enter()
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_DEVICE_BUSY - if the device is busy (try again later)
+ * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
+*/
 extern SANE_Status sanei_scsi_req_wait (void *id);
 
-/* This is a convenience function that is equivalent to a pair of
+/** Send SCSI command
-   enter()/wait() calls.  */
+ *
+ * This is a convenience function that is equivalent to a pair of
+ * sanei_scsi_req_enter()/sanei_scsi_req_wait() calls.
+ *
+ * @param fd file descriptor
+ * @param src pointer to the SCSI command and associated write data (if any)
+ * @param src_size length of the command and data
+ * @param dst pointer to a buffer in which data is returned; NULL if no data is
+ *   returned
+ * @param dst_size  on input, the size of the buffer pointed to by dst, on exit,
+ *   set to the number of bytes returned in the buffer (which is less than or equal
+ *   to the buffer size; may be NULL if no data is expected
+ *
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
+ * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
+ * - SANE_STATUS_INVAL - if a locking or an unknown error occured
+ *
+ * @sa sanei_scsi_cmd2(), sanei_scsi_req_enter(), sanei_scsi_req_wait()
+ */
 extern SANE_Status sanei_scsi_cmd (int fd,
 				   const void * src, size_t src_size,
 				   void * dst, size_t * dst_size);
 
+/** Send SCSI command and separated data
+ *
+ * This is a convenience function that is equivalent to a pair of
+ * sanei_scsi_req_enter2()/sanei_scsi_req_wait() calls.
+ *
+ * @param fd file descriptor
+ * @param cmd pointer to SCSI command
+ * @param cmd_size size of the command
+ * @param src pointer to the buffer with data to be sent to the scanner
+ * @param src_size size of src buffer
+ * @param dst pointer to a buffer in which data is returned; NULL if no data is
+ *   returned
+ * @param dst_size  on input, the size of the buffer pointed to by dst, on exit,
+ *   set to the number of bytes returned in the buffer (which is less than or equal
+ *   to the buffer size; may be NULL if no data is expected
+ * @return
+ * - SANE_STATUS_GOOD - on success
+ * - SANE_STATUS_IO_ERROR - if an error was received from the SCSI driver
+ * - SANE_STATUS_NO_MEM - if malloc failed (not enough memory)
+ * - SANE_STATUS_INVAL - if a locking or an unknown error occured
+ *
+ * @sa sanei_scsi_cmd(), sanei_scsi_req_enter(), sanei_scsi_req_wait()
+ */
 extern SANE_Status sanei_scsi_cmd2 (int fd,
 				   const void * cmd, size_t cmd_size,
 				   const void * src, size_t src_size,
 				   void * dst, size_t * dst_size);
 
-/* Flush all pending SCSI commands. This function work only,
+/** Flush queue
-   if zero or one SCSI file handles are open.
+ *
+ * Flush all pending SCSI commands. This function work only, if zero or one
+ * SCSI file handles are open.
+ *
+ * @sa sanei_scsi_req_flush_all_extended()
 */
 extern void sanei_scsi_req_flush_all (void);
 
-/* Flush all SCSI commands pending for one handle */
+/** Flush queue for handle
+ *
+ * Flush all SCSI commands pending for one handle
+ *
+ * @param fd file descriptor
+ *
+ * @sa sanei_scsi_req_flush_all()
+ */
 extern void sanei_scsi_req_flush_all_extended (int fd);
 
+/** Close a SCSI device
+ *
+ * @param fd file descriptor
+ *
+ */
 extern void sanei_scsi_close (int fd);
 
 #endif /* sanei_scsi_h */