Added, fixed and updated documentation for sanei using doxygen.

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

ChangeLog

@@ -1,3 +1,13 @@
+2002-02-15  Henning Meier-Geinitz <henning@meier-geinitz.de>
+
+	* include/sane/sanei.h include/sane/sanei_ab306.h
+	  include/sane/sanei_auth.h include/sane/sanei_backend.h
+	  include/sane/sanei_codec_ascii.h include/sane/sanei_codec_bin.h
+	  include/sane/sanei_config.h include/sane/sanei_debug.h
+	  include/sane/sanei_lm983x.h include/sane/sanei_thread.h
+	  include/sane/sanei_usb.h: Added, fixed and updated documentation
+	  for sanei using doxygen.
+
 2002-02-15  Stéphane Voltz  <svoltz@wanadoo.fr>
 
 	* backend/umax_pp_low.c backend/umax_pp_low.h backend/umax_pp_mid.h

include/sane/sanei.h

@@ -18,13 +18,15 @@
 */
 
 /** @file sanei.h
- *  Convenience macros and function declarations for backends
+ * Convenience macros and function declarations for backends
+ * @sa sanei_backend.h sanei_thread.h
  */
 
 /* Doxygen documentation */
 
 /** @mainpage SANEI (SANE internal routines) documentation
  *
+ * @image html ../sane-logo2.jpg
  * @section intro Introduction
  *
  * The header files in the include/sane/ directory named sanei_*.h provide
@@ -63,29 +65,21 @@
 
 #include <sane/sane.h>
 
-/* A few convenience macros:  */
+/** @name Public macros and functions
-
+ * @{
+ */
 /** @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])))
+/** @fn extern SANE_Status sanei_constrain_value (const SANE_Option_Descriptor * opt, void * value, SANE_Word * info);
-
-/**
  * 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
@@ -100,6 +94,33 @@
  * - SANE_STATUS_INVAL    - if the function wasn't able to fit value into the
  *   constraint or any other error occured
  */
+/* @} */
+
+/** @name Private macros
+ * @{
+ */
+/** @def STRINGIFY1(x)
+ * Internal use only.
+ */
+/** @def PASTE1(x,y)
+ * Internal use only.
+ */
+/* @} */
+
+/* A few convenience macros:  */
+/** @hideinitializer */
+#define NELEMS(a)	((int)(sizeof (a) / sizeof (a[0])))
+
+/** @hideinitializer */
+#define STRINGIFY1(x)	#x
+/** @hideinitializer */
+#define STRINGIFY(x)	STRINGIFY1(x)
+
+/** @hideinitializer */
+#define PASTE1(x,y)	x##y
+/** @hideinitializer */
+#define PASTE(x,y)	PASTE1(x,y)
+
 extern SANE_Status sanei_constrain_value (const SANE_Option_Descriptor * opt,
 					  void * value, SANE_Word * info);
 

include/sane/sanei_ab306.h

@@ -51,6 +51,8 @@
  *
  * Depending on the operating system it may be necessary to run this code as
  * root.
+ *
+ * @sa sanei_pio.h sanei_scsi.h sanei_usb.h
  */
 
 

include/sane/sanei_auth.h

@@ -37,45 +37,58 @@
    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 user authorization using MD5 digest */
+/** @file sanei_auth.h
+ * Interface for authorization of resources
+ *
+ * This file implements an interface for user authorization. The authorization
+ * call is forwarded to the frontend which asks for a username and password.
+ * An MD5 digest is used if supported by the frontend.
+ *
+ * @sa sanei.h sanei_backend.h
+ */
 
 #ifndef sanei_auth_h
 #define sanei_auth_h
 
 #include "../include/sane/sane.h"
 
-/* this function needs the name of the resource to authorize, the name
+/** Check authorization for a resource
- * of the backend and the auth_callback. It looks for the file:
- * 	SANE_CONFIG_DIR/backend.users
  *
- * if this file doesn't exist, sanei_authorize always returns SANE_STATUS_GOOD
+ * This function looks for the file SANE_CONFIG_DIR/backend.users.
+ * If this file doesn't exist, sanei_authorize always returns SANE_STATUS_GOOD.
+ * The file backend.users contains a list of usernames, passwords, and
+ * resources:
  *
- * the file backend.users contains a list of resource usernames and passwords
+ * username:password:resource
+ * username:password:resource
  *
- * resource:username:password
+ * If the requested resource isn't listed in this file, sanei_authorize
- * resource:username:password
+ * return SANE_SATUS_GOOD. In all other cases, sanei_authorize sends a
- *
+ * challenge to the frontend of the form
- * if the requested resource isn't listed in this file, sanei_authorize
- * return SANE_SATUS_GOOD
- *
- * in all other cases, sanei_authorize sends a challenge to the frontend
- * of the form
  * 
  * resource$MD5$randomstring
  * 
- * where randomstring consists of the PID, the time, and some random characters
+ * where randomstring consists of the PID, the time, and some random
- *
+ * characters. It accepts two forms of answers
- * it accepts two forms of answers
  *
  * std: username:password
  * md5: username:$MD5$m5digest
  *
- * where md5digest is md5(randomstring password)
+ * where md5digest is md5(randomstring password).
  * 
- * if this resource/username/password triple is listed in backend.users
+ * If this username/password/resource triple is listed in backend.users
  * sanei_authorize returns SANE_STATUS_GOOD, in all other cases it returns
- * SANE_STATUS_ACCESS_DENIED
+ * SANE_STATUS_ACCESS_DENIED.
+ *
+ * @param resource resource to authorize
+ * @param backend backend name
+ * @param authorize auth callback
+ *
+ * @return
+ * - SANE_STATUS_GOOD - access is granted
+ * - SANE_STATUS_ACCESS_DENIED - access is denied
  */
 
 SANE_Status

include/sane/sanei_backend.h

@@ -1,3 +1,17 @@
+/** @file sanei_backend.h
+ * Compatibility header file for backends
+ *
+ * This file provides some defines for macros missing on some platforms.
+ * It also has the SANE API entry points. sanei_backend.h muste be included
+ * by every backend.
+ *
+ * @sa sanei.h sanei_thread.h
+ */
+
+/** @name Compatibility macros
+ * @{
+ */
+
 #include <sane/sanei_debug.h>
 
 #ifdef HAVE_SYS_HW_H
@@ -73,9 +87,12 @@
 # define SIG_UNBLOCK    2
 # define SIG_SETMASK    3
 #endif /* !HAVE_SIGPROCMASK */
+/* @} */
 
-/* Declare the entry points: */
 
+/** @name Declaration of entry points:
+ * @{
+ */
 extern SANE_Status ENTRY(init) (SANE_Int *, SANE_Auth_Callback);
 extern SANE_Status ENTRY(get_devices) (const SANE_Device ***, SANE_Bool);
 extern SANE_Status ENTRY(open) (SANE_String_Const, SANE_Handle *);
@@ -110,11 +127,14 @@ extern void ENTRY(exit) (void);
 #define sane_close(a)                   ENTRY(close) (a)
 #define sane_exit(a)                    ENTRY(exit) (a)
 #endif /* STUBS */
+/* @} */
 
-/* Internationalization for SANE backends
+/** @name Internationalization for SANE backends
-   Add SANE_I18N() to all texts that can be translated.
+ * Add SANE_I18N() to all texts that can be translated.
-   E.g. out_txt = SANE_I18N("Hello"); */
+ *  E.g. out_txt = SANE_I18N("Hello"); 
-
+ * @{
+ */
 #ifndef SANE_I18N
 #define SANE_I18N(text) text
 #endif
+/* @} */

include/sane/sanei_codec_ascii.h

@@ -15,12 +15,27 @@
    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 application interface.  See the SANE
+/** @file sanei_codec_ascii.h
-   standard for a detailed explanation of the interface.  */
+ * ASCII codec for network and file transmissions
+ *
+ * Instead translating data to a byte stream this codec uses ASCII hex numbers.
+ * Therefore it can be used for streams that are not 8-bit clean or which can
+ * only use printable characters. It's currently used for saving/restoring
+ * data to/from disk.
+ *
+ * @sa sanei_codec_bin.h sanei_net.h sanei_wire.h
+ */
 #ifndef sanei_codec_ascii_h
 #define sanei_codec_ascii_h
 
+/** Initialize the ascii codec
+ *
+ * Set the i/o functions of the Wire to those of the ASCII codec.
+ *
+ * @param w Wire
+ */
 extern void sanei_codec_ascii_init (Wire *w);
 
 #endif /* sanei_codec_ascii_h */

include/sane/sanei_codec_bin.h

@@ -15,12 +15,25 @@
    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.
+*/
+/** @file sanei_codec_bin.h
+ * Binary codec for network transmissions
+ *
+ * Transtale data to a byte stream while taking byte order problems into
+ * account. This codec is currently used for saned and the network backend.
+ *
+ * @sa sanei_codec_ascii.h sanei_net.h sanei_wire.h
+ */
 
-   This file declares SANE application interface.  See the SANE
-   standard for a detailed explanation of the interface.  */
 #ifndef sanei_codec_bin_h
 #define sanei_codec_bin_h
 
+/** Initialize the binary codec
+ *
+ * Set the i/o functions of the Wire to those of the binary codec.
+ *
+ * @param w Wire
+ */
 extern void sanei_codec_bin_init (Wire *w);
 
 #endif /* sanei_codec_bin_h */

include/sane/sanei_config.h

@@ -40,7 +40,7 @@
 */
 
 /** @file sanei_config.h
- * This file provides generic configuration support.  
+ * Generic configuration support.
  *
  * Use the functions of this header file if you want to read and analyze
  * configuration files.
@@ -77,7 +77,7 @@ extern FILE *sanei_config_open (const char *name);
 */
 extern char *sanei_config_read (char *str, int n, FILE *stream);
 
-/** Removes all whitespace from the beginning of a string.
+/** Remove all whitespace from the beginning of a string.
  *
  * @param str string
  *
@@ -87,7 +87,7 @@ extern char *sanei_config_read (char *str, int n, FILE *stream);
 extern const char *sanei_config_skip_whitespace (const char *str);
 
 
-/** Scans a string constant from a line of text and returns a malloced copy
+/** Scan a string constant from a line of text and return a malloced copy
  * of it.
  *
  * It's the responsibility of the caller to free the returned string constant
@@ -122,6 +122,6 @@ extern const char *sanei_config_get_string (const char *str,
  */
 extern void sanei_config_attach_matching_devices (const char *name,
 						  SANE_Status (*attach)
-						    (const char *dev));
+						  (const char *dev));
 
 #endif	/* sanei_config_h */

include/sane/sanei_debug.h

@@ -1,28 +1,95 @@
+/** @file sanei_debug.h
+ * Support for printing debug messages.
+ *
+ * Use the functions of this header file to print debug or warning messages.
+ */
+
 #ifndef _SANEI_DEBUG_H
 #define _SANEI_DEBUG_H
 
 #include <sane/sanei.h>
 
-/* this header file defines:
+/** @name Public macros
+ * These macros can be used in backends and other SANE-related
+ * code.
  *
- * DBG_INIT() 		 - should be called before any other debug function
+ * Before including sanei_debug.h, the following macros must be set:
- * DBG(level, fmt, ...)	 - prints a message at debug level `level' or higher
- * 			   using a printf-like function
- * IF_DBG(x)             - expands to x if debug support is enabled at
- * 			   compile-time, if NDEBUG is defined at compile-time
- * 			   this macro expands to nothing
  *
- * ENTRY(name)		 - expands to sane_BACKEND_NAME_name
+ * - BACKEND_NAME - The name of your backend without double-quotes (must be set in any case)
- *
+ * - STUBS - If this is defined, no macros will be included. Used in 
- * before you include sanei_debug.h, you'll have to define
+ *   backends consisting of more than one .c file.
- *
+ * - DEBUG_DECLARE_ONLY - Generates prototypes instead of functions. Used in 
- * BACKEND_NAME		 - the name of your backend without double-quotes
+ *   backends consisting of more than one .c file.
- * STUBS                 - if this is defined, nothing will happen
+ * - DEBUG_NOT_STATIC - Doesn't generate static functions. Used in header files if
- * DEBUG_DECLARE_ONLY    - generate prototypes instead of functions
+ *   they are include in more than one .c file.
- * DEBUG_NOT_STATIC	 - doesn't generate static functions
  *
+ * @{ 
  */
 
+/** @def DBG_INIT()
+ * Initialize sanei_debug.
+ *
+ * Call this function before you use any DBG function.
+ */
+
+/** @def DBG(level, fmt, ...)
+ * Print a message at debug level `level' or higher using a printf-like
+ * function. Example: DBG(1, "sane_open: opening fd \%d\\n", fd).
+ *
+ * @param level debug level
+ * @param fmt format (see man 3 printf for details)
+ * @param ... additional arguments
+ */
+
+/** @def IF_DBG(x)
+ * Compile code only if debugging is enabled.
+ *
+ * Expands to x if debug support is enabled at compile-time. If NDEBUG is 
+ * defined at compile-time this macro expands to nothing.
+ *
+ * @param x code to expand when debugging is enabled
+ */
+
+/**
+ * @def DBG_LEVEL
+ * Current debug level. 
+ *
+ * You can only read this "variable".
+ */
+
+/** @def ENTRY(name)
+ * Expands to sane_BACKEND_NAME_name.
+ *
+ * Example: ENTRY(init) in mustek.c will expand to sane_mustek_init.
+ */
+
+/* @} */
+
+/** @name Internal macros and functions
+ * Do not use in your own code.
+ * @{
+ */
+
+/** @def DBG_LOCAL
+ * Do not use in backends directly.
+ *
+ * Internal wrapper for printing function.
+ */
+
+/** @fn extern void sanei_init_debug (const char * backend, int * debug_level_var);
+ * Do not use in backends directly.
+ *
+ * Actual init function.
+ */
+
+/** @fn extern void sanei_debug_msg (int level, int max_level, const char *be, const char *fmt, va_list ap);
+ * Do not use in backends directly.
+ *
+ * Actual printing function.
+ */
+/* @} */
+
+                                  /** @hideinitializer*/
 #define ENTRY(name)     PASTE(PASTE(PASTE(sane_,BACKEND_NAME),_),name)
 
 #ifdef NDEBUG
@@ -36,6 +103,7 @@ extern void sanei_debug_ndebug (int level, const char *msg, ...);
 	
 #else /* !NDEBUG */
 	
+                                  /** @hideinitializer*/
 # define DBG_LEVEL      PASTE(sanei_debug_,BACKEND_NAME)
 
 # if defined(BACKEND_NAME) && !defined(STUBS)
@@ -46,9 +114,11 @@ int DBG_LEVEL = 0;
 #  endif /* DEBUG_DECLARE_ONLY */
 # endif /* BACKEND_NAME && !STUBS */
 
+                                  /** @hideinitializer*/
 # define DBG_INIT()                                     \
   sanei_init_debug (STRINGIFY(BACKEND_NAME), &DBG_LEVEL)
 
+                                  /** @hideinitializer*/
 # define DBG_LOCAL	PASTE(DBG_LEVEL,_call)
 
 
@@ -93,10 +163,12 @@ DBG_LOCAL (int level, const char *msg, ...)
 
 # endif /* !STUBS */
 
+                                  /** @hideinitializer*/
 # define DBG            DBG_LOCAL
 
 extern void sanei_init_debug (const char * backend, int * debug_level_var);
   
+                                  /** @hideinitializer*/
 # define IF_DBG(x)      x
 
 #endif /* NDEBUG */

include/sane/sanei_lm983x.h

@@ -48,6 +48,8 @@
  *
  *  The National Semiconductor LM9831, LM9832, and LM9833 chips are used in
  *  many USB scanners. Examples include Plustek and Mustek devices.
+ *
+ * @sa sanei_usb.h
  */
 
 #ifndef sanei_lm983x_h

include/sane/sanei_thread.h

@@ -31,6 +31,8 @@
  * The preprocessor is used for routing process-related function to OS/2
  * threaded code: in this way, Unix backends requires only minimal code
  * changes.
+ *
+ * @sa sanei.h sanei_backend.h
  */
 
   
@@ -38,6 +40,9 @@
 #define sanei_thread_h
 #include "../include/sane/config.h"
 
+/** @name Internal functions 
+ * @{
+ */
 /** <b>Do not use in backends</b>
  *
  * Wrapper for @c fork. 
@@ -61,6 +66,7 @@ extern int sanei_thread_waitpid( int pid, int *stat_loc, int options);
  * Wrapper for @c wait. 
  */
 extern int sanei_thread_wait( int *stat_loc);
+/* @} */
 
 /** Reader process function.
  *

include/sane/sanei_usb.h

@@ -25,9 +25,9 @@
  * drivers also work. However, detection and control messages aren't
  * supported on these platforms.
  *
- * See <a 
+ * @sa sanei_lm983x.h, sanei_pa4s2.h, sanei_pio.h, sanei_scsi.h, and <a 
  * href="http://www.mostang.com/sane/man/sane-usb.5.html">man sane-usb(5)</a>
- * for user-oriented documentation.
+ * for user-oriented documentation
  */
 
 #ifndef sanei_usb_h