doc: Beautify comments in gpg-error.h.

--

Signed-off-by: Werner Koch <wk@gnupg.org>

1 files changed, 84 insertions, 74 deletions

diff --git a/src/gpg-error.h.in b/src/gpg-error.h.in
index f585808..ce7d278 100644
--- a/src/gpg-error.h.in
+++ b/src/gpg-error.h.in
@@ -1,7 +1,7 @@
-/* gpg-error.h or gpgrt.h - Public interface to libgpg-error.   -*- c -*-
+/* gpg-error.h or gpgrt.h - Common code for GnuPG and others.    -*- c -*-
  * Copyright (C) 2001-2018 g10 Code GmbH
  *
- * This file is part of libgpg-error.
+ * This file is part of libgpg-error (aka libgpgrt).
  *
  * libgpg-error is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public License
@@ -20,6 +20,41 @@
  * @configure_input@
  */
 
+/* The GnuPG project consists of many components.  Error codes are
+ * exchanged between all components.  The common error codes and their
+ * user-presentable descriptions are kept into a shared library to
+ * allow adding new error codes and components without recompiling any
+ * of the other components.  In addition to error codes this library
+ * also features several other groups of functions which are common to
+ * all GnuPG components.  They may be used by independet project as
+ * well.  The interfaces will not change in a backward incompatible way.
+ *
+ * An error code together with an error source build up an error
+ * value.  As the error value is been passed from one component to
+ * another, it preserves the information about the source and nature
+ * of the error.
+ *
+ * A component of the GnuPG project can define the following macros to
+ * tune the behaviour of the library:
+ *
+ * GPG_ERR_SOURCE_DEFAULT: Define to an error source of type
+ * gpg_err_source_t to make that source the default for gpg_error().
+ * Otherwise GPG_ERR_SOURCE_UNKNOWN is used as default.
+ *
+ * GPG_ERR_ENABLE_GETTEXT_MACROS: Define to provide macros to map the
+ * internal gettext API to standard names.  This has only an effect on
+ * Windows platforms.
+ *
+ * GPGRT_ENABLE_ES_MACROS: Define to provide "es_" macros for the
+ * estream functions.
+ *
+ * GPGRT_ENABLE_LOG_MACROS: Define to provide short versions of the
+ * log functions.
+ *
+ * GPGRT_ENABLE_ARGPARSE_MACROS: Needs to be defined to provide the
+ * mandatory macros of the argparse interface.
+ */
+
 #ifndef GPG_ERROR_H
 #define GPG_ERROR_H 1
 #ifndef GPGRT_H
@@ -57,50 +92,17 @@ extern "C" {
 #endif
 #endif /* __cplusplus */
 
-/* The GnuPG project consists of many components.  Error codes are
-   exchanged between all components.  The common error codes and their
-   user-presentable descriptions are kept into a shared library to
-   allow adding new error codes and components without recompiling any
-   of the other components.  The interface will not change in a
-   backward incompatible way.
-
-   An error code together with an error source build up an error
-   value.  As the error value is been passed from one component to
-   another, it preserver the information about the source and nature
-   of the error.
-
-   A component of the GnuPG project can define the following macros to
-   tune the behaviour of the library:
-
-   GPG_ERR_SOURCE_DEFAULT: Define to an error source of type
-   gpg_err_source_t to make that source the default for gpg_error().
-   Otherwise GPG_ERR_SOURCE_UNKNOWN is used as default.
-
-   GPG_ERR_ENABLE_GETTEXT_MACROS: Define to provide macros to map the
-   internal gettext API to standard names.  This has only an effect on
-   Windows platforms.
-
-   GPGRT_ENABLE_ES_MACROS: Define to provide "es_" macros for the
-   estream functions.
-
-   GPGRT_ENABLE_LOG_MACROS: Define to provide short versions of the
-   log functions.
-
-   GPGRT_ENABLE_ARGPARSE_MACROS: Needs to be defined to provide the
-   mandatory macros of the argparse interface.
-
-   In addition to the error codes, Libgpg-error also provides a set of
-   functions used by most GnuPG components.  */
 
 
 /* The error source type gpg_err_source_t.
-
-   Where as the Poo out of a welle small
-   Taketh his firste springing and his sours.
-					--Chaucer.  */
+ *
+ * Where as the Poo out of a welle small
+ * Taketh his firste springing and his sours.
+ *					--Chaucer.
+ */
 
 /* Only use free slots, never change or reorder the existing
-   entries.  */
+ * entries.  */
 typedef enum
   {
 @include:err-sources@
@@ -112,7 +114,7 @@ typedef enum
 /* The error code type gpg_err_code_t.  */
 
 /* Only use free slots, never change or reorder the existing
-   entries.  */
+ * entries.  */
 typedef enum
   {
 @include:err-codes@
@@ -127,13 +129,13 @@ typedef enum
 /* The error value type gpg_error_t.  */
 
 /* We would really like to use bit-fields in a struct, but using
-   structs as return values can cause binary compatibility issues, in
-   particular if you want to do it efficiently (also see
-   -freg-struct-return option to GCC).  */
+ * structs as return values can cause binary compatibility issues, in
+ * particular if you want to do it efficiently (also see
+ * -freg-struct-return option to GCC).  */
 typedef unsigned int gpg_error_t;
 
 /* We use the lowest 16 bits of gpg_error_t for error codes.  The 16th
-   bit indicates system errors.  */
+ * bit indicates system errors.  */
 #define GPG_ERR_CODE_MASK	(GPG_ERR_CODE_DIM - 1)
 
 /* Bits 17 to 24 are reserved.  */
@@ -143,11 +145,13 @@ typedef unsigned int gpg_error_t;
 #define GPG_ERR_SOURCE_SHIFT	24
 
 /* The highest bit is reserved.  It shouldn't be used to prevent
-   potential negative numbers when transmitting error values as
-   text.  */
+ * potential negative numbers when transmitting error values as
+ * text.  */
 
 
-/* GCC feature test.  */
+/*
+ * GCC feature test.
+ */
 #if __GNUC__
 # define _GPG_ERR_GCC_VERSION (__GNUC__ * 10000 \
                                + __GNUC_MINOR__ * 100 \
@@ -208,9 +212,9 @@ typedef unsigned int gpg_error_t;
 #endif
 
 /* The used and unused attributes.
-   I am not sure since when the unused attribute is really supported.
-   In any case it it only needed for gcc versions which print a
-   warning.  Thus let us require gcc >= 3.5.  */
+ * I am not sure since when the unused attribute is really supported.
+ * In any case it it only needed for gcc versions which print a
+ * warning.  Thus let us require gcc >= 3.5.  */
 #if _GPG_ERR_GCC_VERSION >= 40000
 # define GPGRT_ATTR_USED  __attribute__ ((used))
 #else
@@ -290,7 +294,9 @@ gpgrt_annotate_leaked_object (const void *p)
 }
 
 
-/* Initialization function.  */
+/*
+ * Initialization function.
+ */
 
 /* Initialize the library.  This function should be run early.  */
 gpg_error_t gpg_err_init (void) _GPG_ERR_CONSTRUCTOR;
@@ -320,10 +326,12 @@ void gpgrt_set_alloc_func  (void *(*f)(void *a, size_t n));
 
 
 
-/* Constructor and accessor functions.  */
+/*
+ * Constructor and accessor functions.
+ */
 
 /* Construct an error value from an error code and source.  Within a
-   subsystem, use gpg_error.  */
+ * subsystem, use gpg_error.  */
 static GPG_ERR_INLINE gpg_error_t
 gpg_err_make (gpg_err_source_t source, gpg_err_code_t code)
 {
@@ -334,7 +342,7 @@ gpg_err_make (gpg_err_source_t source, gpg_err_code_t code)
 
 
 /* The user should define GPG_ERR_SOURCE_DEFAULT before including this
-   file to specify a default source for gpg_error.  */
+ * file to specify a default source for gpg_error.  */
 #ifndef GPG_ERR_SOURCE_DEFAULT
 #define GPG_ERR_SOURCE_DEFAULT	GPG_ERR_SOURCE_UNKNOWN
 #endif
@@ -366,44 +374,44 @@ gpg_err_source (gpg_error_t err)
 /* String functions.  */
 
 /* Return a pointer to a string containing a description of the error
-   code in the error value ERR.  This function is not thread-safe.  */
+ * code in the error value ERR.  This function is not thread-safe.  */
 const char *gpg_strerror (gpg_error_t err);
 
 /* Return the error string for ERR in the user-supplied buffer BUF of
-   size BUFLEN.  This function is, in contrast to gpg_strerror,
-   thread-safe if a thread-safe strerror_r() function is provided by
-   the system.  If the function succeeds, 0 is returned and BUF
-   contains the string describing the error.  If the buffer was not
-   large enough, ERANGE is returned and BUF contains as much of the
-   beginning of the error string as fits into the buffer.  */
+ * size BUFLEN.  This function is, in contrast to gpg_strerror,
+ * thread-safe if a thread-safe strerror_r() function is provided by
+ * the system.  If the function succeeds, 0 is returned and BUF
+ * contains the string describing the error.  If the buffer was not
+ * large enough, ERANGE is returned and BUF contains as much of the
+ * beginning of the error string as fits into the buffer.  */
 int gpg_strerror_r (gpg_error_t err, char *buf, size_t buflen);
 
 /* Return a pointer to a string containing a description of the error
-   source in the error value ERR.  */
+ * source in the error value ERR.  */
 const char *gpg_strsource (gpg_error_t err);
 
 
-/* Mapping of system errors (errno).  */
+/*
+ * Mapping of system errors (errno).
+ */
 
 /* Retrieve the error code for the system error ERR.  This returns
-   GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
-   this). */
+ * GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
+ * this). */
 gpg_err_code_t gpg_err_code_from_errno (int err);
 
-
 /* Retrieve the system error for the error code CODE.  This returns 0
-   if CODE is not a system error code.  */
+ * if CODE is not a system error code.  */
 int gpg_err_code_to_errno (gpg_err_code_t code);
 
-
 /* Retrieve the error code directly from the ERRNO variable.  This
-   returns GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped
-   (report this) and GPG_ERR_MISSING_ERRNO if ERRNO has the value 0. */
+ * returns GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped
+ * (report this) and GPG_ERR_MISSING_ERRNO if ERRNO has the value 0. */
 gpg_err_code_t gpg_err_code_from_syserror (void);
 
 
 /* Set the ERRNO variable.  This function is the preferred way to set
-   ERRNO due to peculiarities on WindowsCE.  */
+ * ERRNO due to peculiarities on WindowsCE.  */
 void gpg_err_set_errno (int err);
 
 /* Return or check the version.  Both functions are identical.  */
@@ -1252,7 +1260,9 @@ typedef struct
 
 #endif /* GPGRT_ENABLE_ARGPARSE_MACROS */
 
-
+/* Take care: gpgrt_argparse keeps state in ARG and requires that
+ * either ARGPARSE_FLAG_RESET is used after OPTS has been changed or
+ * gpgrt_argparse (NULL, ARG, NULL) is called first.  */
 int gpgrt_argparse (gpgrt_stream_t fp,
                     gpgrt_argparse_t *arg, gpgrt_opt_t *opts);
 void gpgrt_usage (int level);