[SCM] GNU shishi branch, master, updated. shishi-1-0-2-33-g9062a20

[Mats Erik Andersson]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU shishi".

http://git.savannah.gnu.org/cgit/shishi.git/commit/?id=9062a2023e9060d3a05a968f10ad30e9e1bf5c2a

The branch, master has been updated
       via  9062a2023e9060d3a05a968f10ad30e9e1bf5c2a (commit)
      from  8e5585a9318aa7e503c3f379ee4a720262774e57 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 9062a2023e9060d3a05a968f10ad30e9e1bf5c2a
Author: Mats Erik Andersson <address@hidden>
Date:   Thu Jun 26 20:56:01 2014 +0200

    Updated API docs, mainly for shisa.
    
    Also suppress empty argument section in man pages.

-----------------------------------------------------------------------

Summary of changes:
 db/config.c   |   39 +++++++----
 db/core.c     |  213 ++++++++++++++++++++++++++++++++-------------------------
 db/err.c      |   17 +++--
 db/setup.c    |   43 ++++++------
 doc/gdoc      |   30 +++++---
 lib/gztime.c  |   64 ++++++++++--------
 lib/version.c |   15 +++--
 7 files changed, 241 insertions(+), 180 deletions(-)

diff --git a/db/config.c b/db/config.c
index cdc9b7b..4a10773 100644
--- a/db/config.c
+++ b/db/config.c
@@ -25,15 +25,18 @@
 /**
  * shisa_cfg_db:
  * @dbh: Shisa library handle created by shisa().
- * @value: string with database definition.
+ * @value: String containing database definition.
  *
- * Setup and open a new database.  The syntax of the @value parameter
- * is "TYPE[ LOCATION[ PARAMETER]]", where TYPE is one of the
- * supported database types (e.g., "file") and LOCATION and PARAMETER
- * are optional strings passed to the database during initialization.
- * Neither TYPE nor LOCATION can contain " " (SPC), but PARAMETER may.
+ * Sets up and opens a new database.  The syntax of the parameter
+ * @value is "TYPE[ LOCATION[ PARAMETER]]", where TYPE is one of the
+ * supported database types, typically "file", and LOCATION as
+ * well as PARAMETER are optional strings passed on to
+ * the database during initialization.
  *
- * Return Value: Returns %SHISA_OK if database was parsed and open
+ * Neither TYPE nor LOCATION may contain embedded spaces,
+ * but PARAMETER may do so.
+ *
+ * Return Value: Returns %SHISA_OK if a database was parsed and opened
  *   successfully.
  **/
 int
@@ -88,11 +91,17 @@ shisa_cfg_db (Shisa * dbh, const char *value)
 /**
  * shisa_cfg:
  * @dbh: Shisa library handle created by shisa().
- * @option: string with shisa library option.
+ * @option: String with options to prime the Shisa library.
+ *
+ * Configures the Shisa library from the specification @option.
+ * This call expects a string declaration of the form "db=VALUE"
+ * or "db VALUE", where VALUE is of the form
+ * "TYPE[ LOCATION[ PARAMETER]]", as is described for
+ * shisa_cfg_db().
  *
- * Configure shisa library with given option.
+ * Thus shisa_cfg() comes closer to a syntax with key-value pairs.
  *
- * Return Value: Returns SHISA_OK if option was valid.
+ * Return Value: Returns %SHISA_OK if @option is valid.
  **/
 int
 shisa_cfg (Shisa * dbh, const char *option)
@@ -118,9 +127,10 @@ shisa_cfg (Shisa * dbh, const char *option)
 /**
  * shisa_cfg_from_file:
  * @dbh: Shisa library handle created by shisa().
- * @cfg: filename to read configuration from.
+ * @cfg: File name where to read configuration.
  *
- * Configure shisa library using configuration file.
+ * Configures the Shisa library using a configuration file
+ * located at @cfg.
  *
  * Return Value: Returns %SHISA_OK iff successful.
  **/
@@ -188,7 +198,10 @@ shisa_cfg_from_file (Shisa * dbh, const char *cfg)
  * shisa_cfg_default_systemfile:
  * @dbh: Shisa library handle created by shisa().
  *
- * Return value: Return system configuration filename.
+ * Recovers information on the installed configuration.
+ *
+ * Return value: Returns the file name of the active
+ *   system configuration.
  **/
 const char *
 shisa_cfg_default_systemfile (Shisa * dbh)
diff --git a/db/core.c b/db/core.c
index aac2aa6..03030e5 100644
--- a/db/core.c
+++ b/db/core.c
@@ -25,14 +25,16 @@
 /**
  * shisa_enumerate_realms:
  * @dbh: Shisa library handle created by shisa().
- * @realms: Pointer to newly allocated array of newly allocated
- *   zero-terminated UTF-8 strings indicating name of realm.
- * @nrealms: Pointer to number indicating number of allocated realm strings.
+ * @realms: Returned pointer to a newly allocated array of also
+ *   allocated and null-terminated UTF-8 strings with realm names.
+ * @nrealms: Pointer to a number which is updated with the number
+ *   of just allocated and returned realm strings.
  *
- * Extract a list of all realm names in backend, as zero-terminated
- * UTF-8 strings.  The caller must deallocate the strings.
+ * Extracts a list of all realm names in backend, as null-terminated
+ * UTF-8 strings.  The caller is responsible for deallocating all
+ * strings as well as the array address@hidden
  *
- * Return value: Returns SHISA_OK on success, or error code.
+ * Return value: Returns %SHISA_OK on success, or an error code.
  **/
 int
 shisa_enumerate_realms (Shisa * dbh, char ***realms, size_t * nrealms)
@@ -59,18 +61,19 @@ shisa_enumerate_realms (Shisa * dbh, char ***realms, size_t 
* nrealms)
 /**
  * shisa_enumerate_principals:
  * @dbh: Shisa library handle created by shisa().
- * @realm: Name of realm, as zero-terminated UTF-8 string.
- * @principal: Pointer to newly allocated array of newly allocated
- *   zero-terminated UTF-8 strings indicating name of principal.
- * @nprincipals: Pointer to number indicating number of allocated
- *   realm strings.
+ * @realm: Name of realm, as null-terminated UTF-8 string.
+ * @principals: Returned pointer to newly allocated array of just
+ *   allocated null-terminated UTF-8 strings with principal names.
+ * @nprincipals: Pointer to number updated with the number of just
+ *   allocated and returned principal names.
  *
- * Extract a list of all principal names in realm in backend, as
- * zero-terminated UTF-8 strings.  The caller must deallocate the
- * strings.
+ * Extracts a list of all principal names in backend belonging to
+ * the realm @realm, as null-terminated UTF-8 strings.  The caller
+ * is responsible for deallocating all strings and the array
+ * address@hidden
  *
- * Return value: Returns SHISA_OK on success, SHISA_NO_REALM if the
- *   specified realm does not exist, or error code.
+ * Return value: Returns %SHISA_OK on success, %SHISA_NO_REALM if the
+ *   specified realm does not exist, or an error code otherwise.
  **/
 int
 shisa_enumerate_principals (Shisa * dbh,
@@ -100,16 +103,17 @@ shisa_enumerate_principals (Shisa * dbh,
 /**
  * shisa_principal_find:
  * @dbh: Shisa library handle created by shisa().
- * @realm: Name of realm the principal belongs in.
- * @principal: Name of principal to get information on.
- * @ph: Pointer to previously allocated principal structure to fill
- *   out with information about principal.
+ * @realm: Name of the realm the principal belongs to.
+ * @principal: Name of principal to get information about.
+ * @ph: Pointer to a previously allocated principal structure
+ *   where information about the principal is to be stored.
  *
- * Extract information about given address@hidden
+ * Extracts information about given the address@hidden pair
+ * selected by @principal and @realm.
  *
  * Return value: Returns %SHISA_OK iff successful, %SHISA_NO_REALM if
  *   the indicated realm does not exist, %SHISA_NO_PRINCIPAL if the
- *   indicated principal does not exist, or an error code.
+ *   indicated principal does not exist, or an error code otherwise.
  **/
 int
 shisa_principal_find (Shisa * dbh,
@@ -133,23 +137,26 @@ shisa_principal_find (Shisa * dbh,
 /**
  * shisa_principal_update:
  * @dbh: Shisa library handle created by shisa().
- * @realm: Name of realm the principal belongs in.
- * @principal: Name of principal to get information on.
- * @ph: Pointer to principal structure with information to store in database.
+ * @realm: Name of the realm the principal belongs to.
+ * @principal: Name of principal to get information about.
+ * @ph: Pointer to an existing principal structure containing
+ * information to store in the database.
  *
- * Modify information stored for given address@hidden  Note that it
- * is usually a good idea to only set the fields in @ph that you
- * actually want to update.  Specifically, first calling
- * shisa_principal_find() to get the current information, then
- * modifying one field, and calling shisa_principal_update() is not
- * recommended in general, as this will 1) overwrite any modifications
- * made to other fields between the two calls (by other processes) and
+ * Modifies information stored about the given principal
+ * address@hidden  Note that it is usually a good idea to set
+ * in @ph only the fields that are to be updated.
+ * Specifically, it is recommended to first call
+ * shisa_principal_find() to get the current information, then to
+ * modify one field and call shisa_principal_update().
+ * Modifying several values is not recommended in general,
+ * as this will 1) overwrite any modifications made to other fields
+ * between the two calls (by other processes) and
  * 2) will cause all values to be written again, which may generate
  * more overhead.
  *
- * Return value: Returns SHISA_OK if successful, %SHISA_NO_REALM if
+ * Return value: Returns %SHISA_OK if successful, %SHISA_NO_REALM if
  *   the indicated realm does not exist, %SHISA_NO_PRINCIPAL if the
- *   indicated principal does not exist, or an error code.
+ *   indicated principal does not exist, or an error code otherwise.
  **/
 int
 shisa_principal_update (Shisa * dbh,
@@ -175,15 +182,21 @@ shisa_principal_update (Shisa * dbh,
 /**
  * shisa_principal_add:
  * @dbh: Shisa library handle created by shisa().
- * @realm: Name of realm the principal belongs in.
- * @principal: Name of principal to add, may be %NULL to indicate that
- *   the @realm should be created, in which case @ph and @key are not used.
- * @ph: Pointer to principal structure with information to store in database.
- * @key: Pointer to key structure with information to store in database.
+ * @realm: Name of the realm the principal belongs to.
+ * @principal: Name of principal to add.  When set to %NULL,
+ *   only the realm @realm is created.
+ * @ph: Pointer to a principal structure with information to store
+ *   in the database.
+ * @key: Pointer to a key structure with information to store in
+ *   the database.
  *
- * Add given information to database as address@hidden
+ * Inserts the given information into the database for the
+ * principal address@hidden  In case @principal is %NULL,
+ * the prameters @ph and @key are not used and only the realm
+ * added to the database.
  *
- * Return value: Returns SHISA_OK iff successfully added, or an error code.
+ * Return value: Returns %SHISA_OK iff successfully added,
+ *   or an error code.
  **/
 int
 shisa_principal_add (Shisa * dbh,
@@ -213,12 +226,16 @@ shisa_principal_add (Shisa * dbh,
 /**
  * shisa_principal_remove:
  * @dbh: Shisa library handle created by shisa().
- * @realm: Name of realm the principal belongs in.
- * @principal: Name of principal to remove, may be %NULL to indicate
+ * @realm: Name of the realm the principal belongs to.
+ * @principal: Name of principal to remove.  Set to %NULL,
+ *   only the realm @realm is removed.
  *   that the @realm itself should be removed (requires that the realm
  *   to be empty).
  *
- * Remove all information stored in the database for given address@hidden
+ * Removes all information stored in the database for the given
+ * principal address@hidden  When @principal is %NULL, then the
+ * realm @realm is itself remove, but this will only succeed if
+ * the realm is already empty.
  *
  * Return value: Returns %SHISA_OK if successful, or an error code.
  **/
@@ -246,18 +263,22 @@ shisa_principal_remove (Shisa * dbh, const char *realm, 
const char *principal)
 /**
  * shisa_keys_find:
  * @dbh: Shisa library handle created by shisa().
- * @realm: Name of realm the principal belongs in.
- * @principal: Name of principal to add key for.
- * @hint: Pointer to Shisa key structure with hints on matching the key
- *   to modify, may be %NULL to match all keys.
- * @keys: pointer to newly allocated array with Shisa key structures.
- * @nkeys: pointer to number of newly allocated Shisa key structures in @keys.
+ * @realm: Name of the realm the principal belongs to.
+ * @principal: Name of the principal whose keys are examined.
+ * @hint: Pointer to a Shisa key structure with hints on matching
+ *   criteria for relevant keys.  %NULL matches all keys.
+ * @keys: Returned pointer to a newly allocated array of Shisa
+ *   key structures.
+ * @nkeys: Pointer to number updated with the number of allocated
+ *   Shisa key structures in address@hidden
  *
- * Iterate through keys for given address@hidden and extract any keys
- * that match @hint.  Not all elements of @hint need to be filled out,
- * only use the fields you are interested in.  For example, if you
- * want to extract all keys with an etype of 3 (DES-CBC-MD5), set the
- * @key->etype field to 3, and set all other fields to 0.
+ * Iterates through the set of keys belonging to the principal
+ * address@hidden, as specified by @principal and @realm,
+ * and then extracts any keys that match the criteria in @hint.
+ * Not all elements of @hint need to be filled out.
+ * Set only the fields you are interested in.  For example, if you
+ * want to extract all keys with an etype of 3, i.e., DES-CBC-MD5,
+ * set the @key->etype field to 3, and all other fields to 0.
  *
  * Return value: Returns %SHISA_OK iff successful, or an error code.
  **/
@@ -290,11 +311,12 @@ shisa_keys_find (Shisa * dbh,
 /**
  * shisa_key_add:
  * @dbh: Shisa library handle created by shisa().
- * @realm: Name of realm the principal belongs in.
- * @principal: Name of principal to add key for.
- * @key: Pointer to Shisa key structure with key to add.
+ * @realm: Name of the realm the principal belongs to.
+ * @principal: Name of the principal to add a new key for.
+ * @key: Pointer to a Shisa key structure with the new key.
  *
- * Add key to database for given address@hidden
+ * Adds @key to the database entry belonging to the
+ * principal address@hidden, built from @principal and @realm.
  *
  * Return value: Returns %SHISA_OK iff successful, or an error code.
  **/
@@ -321,27 +343,29 @@ shisa_key_add (Shisa * dbh,
 /**
  * shisa_key_update:
  * @dbh: Shisa library handle created by shisa().
- * @realm: Name of realm the principal belongs in.
- * @principal: Name of principal to remove key for.
- * @oldkey: Pointer to Shisa key structure with hints on matching the key
- *   to modify.
- * @newkey: Pointer to Shisa key structure with new values for the
- *   key, note that all fields are used (and not just the ones specified
- *   by @oldkey).
+ * @realm: Name of the realm the principal belongs to.
+ * @principal: Name of the principal needing an updated key.
+ * @oldkey: Pointer to a Shisa key structure giving matching
+ *   criteria for locating the key to be updated.
+ * @newkey: Pointer to a complete Shisa key structure, in which
+ *   all fields are used for the new key.  Note that @oldkey
+ *   normally has far fewer fields filled-in.
  *
- * Modify data about a key in the database, for the given
- * address@hidden  First the @oldkey is used to locate the key to
- * update (similar to shisa_keys_find()), then that key is modified to
- * contain whatever information is stored in @newkey.  Not all
- * elements of @oldkey need to be filled out, only enough as to
- * identify the key uniquely.  For example, if you want to modify the
- * information stored for the only key with an etype of 3
- * (DES-CBC-MD5), set the @key->etype field to 3, and set all other
- * fields to 0.
+ * Modifies data about a key stored in the database, a key belonging
+ * to the principal built from @principal and @realm.
+ * First @oldkey is used to locate the key to
+ * update (similar to shisa_keys_find()), then found key is
+ * modified to contain whatever information is stored in @newkey.
+ * Not all elements of @oldkey need to be filled out, only sufficiently
+ * man so as to uniquely identify the desired key.
+ * For example, if you want to modify the information stored for
+ * the only key with an etype of 3, * i.e., DES-CBC-MD5,
+ * then set the @key->etype field to 3, and all other fields to 0.
  *
- * Return value: Returns %SHISA_OK on success, %SHISA_NO_KEY if no key
- *   could be identified, and %SHISA_MULTIPLE_KEY_MATCH if more than one
- *   key matched the given criteria, or an error code.
+ * Return value: Returns %SHISA_OK on success, %SHISA_NO_KEY if no
+ *   key could be located , %SHISA_MULTIPLE_KEY_MATCH if more
+ *   than a single key matched the given criteria, or an error code
+ *   otherwise.
  **/
 int
 shisa_key_update (Shisa * dbh,
@@ -367,20 +391,21 @@ shisa_key_update (Shisa * dbh,
 /**
  * shisa_key_remove:
  * @dbh: Shisa library handle created by shisa().
- * @realm: Name of realm the principal belongs in.
- * @principal: Name of principal to remove key for.
- * @key: Pointer to Shisa key structure with hints on matching the key
- *   to remove.
+ * @realm: Name of the realm the principal belongs to.
+ * @principal: Name of the principal whose key is to be removed.
+ * @key: Pointer to a Shisa key structure with hints on matching
+ *   criteria for the key to be removed.
  *
- * Remove a key, matching the hints in @key, from the Shisa database
+ * Removes from the Shisa database a key, matching the hints in @key,
  * for the user address@hidden  Not all elements of @key need to be
- * filled out, only those you are interested in.  For example, if you
- * want to remove the only key with an etype of 3 (DES-CBC-MD5), set
- * the @key->etype field to 3, and set all other fields to 0.
+ * filled in, only those relevant to locate the key.  For example,
+ * if you want to remove the only key with an etype of 3, i.e.,
+ * DES-CBC-MD5, set the @key->etype field to 3, and all other
+ * fields to 0.
  *
  * Return value: Returns %SHISA_OK on success, %SHISA_NO_KEY if no key
- *   could be identified, and %SHISA_MULTIPLE_KEY_MATCH if more than one
- *   key matched the given criteria, or an error code.
+ *   could be located, %SHISA_MULTIPLE_KEY_MATCH if more than one
+ *   key matched the given criteria, or an error code otherwise.
  **/
 int
 shisa_key_remove (Shisa * dbh,
@@ -404,9 +429,9 @@ shisa_key_remove (Shisa * dbh,
 /**
  * shisa_key_free:
  * @dbh: Shisa library handle created by shisa().
- * @key: Pointer to Shisa key structure to deallocate.
+ * @key: Pointer to a Shisa key structure to be deallocated.
  *
- * Deallocate the fields of a Shisa key structure, and the structure
+ * Deallocates the fields of a Shisa key structure, and the structure
  * itself.
  **/
 void
@@ -423,11 +448,11 @@ shisa_key_free (Shisa * dbh, Shisa_key * key)
 /**
  * shisa_keys_free:
  * @dbh: Shisa library handle created by shisa().
- * @keys: Pointer to array with @nkeys elements of keys.
- * @nkeys: Number of key elements in @keys array.
+ * @keys: Pointer to an array of Shisa key structures, @nkeys in number.
+ * @nkeys: Number of key elements in the array @keys.
  *
- * Deallocate each element of an array with Shisa database keys, using
- * shisa_key_free().
+ * Deallocates each key element in an array of Shisa database keys,
+ * using repeated calls to shisa_key_free().
  **/
 void
 shisa_keys_free (Shisa * dbh, Shisa_key ** keys, size_t nkeys)
diff --git a/db/err.c b/db/err.c
index db108fe..ba7fe59 100644
--- a/db/err.c
+++ b/db/err.c
@@ -79,11 +79,14 @@ static const struct shisa_error_msgs 
_shisa_error_messages[] = {
 
 /**
  * shisa_strerror:
- * @err: shisa error code
+ * @err: Shisa error code.
  *
- * Return value: Returns a pointer to a statically allocated string
- * containing a description of the error with the error value @err.
- * This string can be used to output a diagnostic message to the user.
+ * Explains verbally an error status @err.
+ * The returned string can be used to compose a diagnostic
+ * message of benefit to a user.
+ *
+ * Return value: Returns a pointer to a statically allocated string,
+ * containing a description of the error given as input argument.
  **/
 const char *
 shisa_strerror (int err)
@@ -101,10 +104,10 @@ shisa_strerror (int err)
 /**
  * shisa_info:
  * @dbh: Shisa library handle created by shisa().
- * @format: printf style format string.
- * @...: print style arguments.
+ * @format: printf(3) style format string.
+ * @...: printf(3) style arguments.
  *
- * Print informational message to standard error.
+ * Prints an informational message to standard error.
  **/
 void
 shisa_info (Shisa * dbh, const char *format, ...)
diff --git a/db/setup.c b/db/setup.c
index 9b87fdb..2309556 100644
--- a/db/setup.c
+++ b/db/setup.c
@@ -26,9 +26,9 @@
  * shisa:
  *
  * Initializes the Shisa library.  If this function fails, it may
- * print diagnostic errors to stderr.
+ * print diagnostic errors to standard error.
  *
- * Return value: Returns Shisa library handle, or %NULL on error.
+ * Return value: Returns a Shisa library handle, or %NULL on error.
  **/
 Shisa *
 shisa (void)
@@ -45,10 +45,10 @@ shisa (void)
 
 /**
  * shisa_done:
- * @handle: shisa handle as allocated by shisa().
+ * @dbh: Shisa handle as allocated by shisa().
  *
  * Deallocates the shisa library handle.  The handle must not be used
- * in any calls to shisa functions after this.
+ * in calls to any shisa function after the completion of this call.
  **/
 void
 shisa_done (Shisa * dbh)
@@ -65,18 +65,19 @@ shisa_done (Shisa * dbh)
 
 /**
  * shisa_init:
- * @dbh: pointer to library handle to be created.
+ * @dbh: Returned pointer to a created Shisa library handle.
  *
- * Create a Shisa library handle, using shisa(), and read the system
- * configuration file from their default locations.  The paths to the
+ * Creates a Shisa library handle, using shisa(), and reads the system
+ * configuration file from its default location.  The path to the
  * default system configuration file is decided at compile time
  * ($sysconfdir/shisa.conf).
  *
- * The handle is allocated regardless of return values, except for
- * SHISA_INIT_ERROR which indicates a problem allocating the handle.
- * (The other error conditions comes from reading the files.)
+ * The handle is allocated regardless of return value, except for
+ * %SHISA_INIT_ERROR which indicates a problem in allocating the
+ * handle.  Other error conditions arise while reading a file.
  *
- * Return value: Returns %SHISA_OK iff successful.
+ * Return value: Returns %SHISA_OK, or an error code.  The error
+ *   code %SHISA_INIT_ERROR indicates a failure to create the handle.
  **/
 int
 shisa_init (Shisa ** dbh)
@@ -86,19 +87,21 @@ shisa_init (Shisa ** dbh)
 
 /**
  * shisa_init_with_paths:
- * @dbh: pointer to library handle to be created.
- * @file: Filename of system configuration, or NULL.
+ * @dbh: Returned pointer to a created Shisa library handle.
+ * @file: Filename of system configuration, or %NULL.
  *
- * Create a Shisa library handle, using shisa(), and read the system
- * configuration file indicated location (or the default location, if
- * %NULL).  The paths to the default system configuration file is
+ * Creates a Shisa library handle, using shisa(), and reads the system
+ * configuration file from the indicated location at @file, or at the
+ * default location, should @file be %NULL.
+ * The path to the default system configuration file is
  * decided at compile time ($sysconfdir/shisa.conf).
  *
- * The handle is allocated regardless of return values, except for
- * SHISA_INIT_ERROR which indicates a problem allocating the handle.
- * (The other error conditions comes from reading the files.)
+ * The handle is allocated regardless of return value, except for
+ * %SHISA_INIT_ERROR which indicates a problem in allocating the
+ * handle.  Other error conditions arise while reading a file.
  *
- * Return value: Returns %SHISA_OK iff successful.
+ * Return value: Returns %SHISA_OK, or an error code.  The error
+ *   %SHISA_INIT_ERROR indicates a failure to create the handle.
  **/
 int
 shisa_init_with_paths (Shisa ** dbh, const char *file)
diff --git a/doc/gdoc b/doc/gdoc
index b7cd237..1848052 100755
--- a/doc/gdoc
+++ b/doc/gdoc
@@ -734,8 +734,10 @@ sub output_man {
     print ".BI \"".$args{'functiontype'}." ".$args{'function'}."(";
     $count = 0;
     foreach $parameter (@{$args{'parameterlist'}}) {
-       print $args{'parametertypes'}{$parameter},
-             ' " ', $parameter, ' "',
+       print $args{'parametertypes'}{$parameter}, ' '
+           if $args{'parametertypes'}{$parameter};
+
+       print '" ', $parameter, ' "',
              $args{'arraylength'}{$parameter};
 
        if ($count != $#{$args{'parameterlist'}}) {
@@ -745,18 +747,22 @@ sub output_man {
     }
     print ");\"\n";
 
-    print ".SH ARGUMENTS\n";
-    foreach $parameter (@{$args{'parameterlist'}}) {
-       print '.IP "';
-       # Variadic arguments carry no type.
-       print $args{'parametertypes'}{$parameter}, ' '
-           if $args{'parametertypes'}{$parameter};
-       print $parameter, $args{'arraylength'}{$parameter}, "\" 12\n";
+    if (@{$args{'parameterlist'}}) {
+       print ".SH ARGUMENTS\n";
+       foreach $parameter (@{$args{'parameterlist'}}) {
+           print '.IP "';
+           # Variadic arguments carry no type.
+           print $args{'parametertypes'}{$parameter}, ' '
+               if $args{'parametertypes'}{$parameter};
+           print $parameter, $args{'arraylength'}{$parameter},
+                 "\" 12\n";
 
-       $param = $args{'parameters'}{$parameter};
-       $param =~ s/-/\\-/g;
-       output_highlight($param);
+           $param = $args{'parameters'}{$parameter};
+           $param =~ s/-/\\-/g;
+           output_highlight($param);
+       }
     }
+
     foreach $section (@{$args{'sectionlist'}}) {
        print ".SH \"" . uc($section) . "\"\n";
        $sec = $args{'sections'}{$section};
diff --git a/lib/gztime.c b/lib/gztime.c
index 629879d..650fc79 100644
--- a/lib/gztime.c
+++ b/lib/gztime.c
@@ -27,13 +27,14 @@
 
 /**
  * shishi_generalize_time:
- * @handle: shishi handle as allocated by shishi_init().
+ * @handle: Shishi handle as allocated by shishi_init().
  * @t: C time to convert.
  *
- * Convert C time to KerberosTime.  The string must not be deallocate
- * by caller.
+ * Converts C time @t to a KerberosTime string representation.
+ * The returned string must not be deallocated by the caller.
  *
- * Return value: Return a KerberosTime time string corresponding to C time t.
+ * Return value: Returns a KerberosTime formatted string
+ *    corresponding to the input parameter.
  **/
 const char *
 shishi_generalize_time (Shishi * handle, time_t t)
@@ -49,13 +50,13 @@ shishi_generalize_time (Shishi * handle, time_t t)
 
 /**
  * shishi_generalize_now:
- * @handle: shishi handle as allocated by shishi_init().
+ * @handle: Shishi handle as allocated by shishi_init().
  *
- * Convert current time to KerberosTime.  The string must not be
- * deallocate by caller.
+ * Converts the current time to a KerberosTime string.
+ * The returned string must not be deallocated by the caller.
  *
- * Return value: Return a KerberosTime time string corresponding to
- *   current time.
+ * Return value: Returns a KerberosTime formatted string
+ *   corresponding to the current time.
  **/
 const char *
 shishi_generalize_now (Shishi * handle)
@@ -67,12 +68,14 @@ shishi_generalize_now (Shishi * handle)
 
 /**
  * shishi_generalize_ctime:
- * @handle: shishi handle as allocated by shishi_init().
- * @t: KerberosTime to convert.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @t: KerberosTime string to convert.
  *
- * Convert KerberosTime to C time.
+ * Converts a KerberosTime formatted string in @t to
+ * integral C time representation.
  *
- * Return value: Returns C time corresponding to KerberosTime t.
+ * Return value: Returns the C time corresponding to the input
+ *   argument.
  **/
 time_t
 shishi_generalize_ctime (Shishi * handle, const char *t)
@@ -95,14 +98,17 @@ shishi_generalize_ctime (Shishi * handle, const char *t)
 
 /**
  * shishi_time:
- * @handle: shishi handle as allocated by shishi_init().
- * @node: ASN.1 node to get time from.
- * @field: Name of field in ASN.1 node to get time from.
- * @t: newly allocated output array with zero terminated time string.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @node: ASN.1 structure to get time from.
+ * @field: Name of the field in the ASN.1 node carrying time.
+ * @t: Returned pointer to an allocated char array containing
+ *   a null-terminated time string.
  *
- * Extract time from ASN.1 structure.
+ * Extracts time information from an ASN.1 structure,
+ * and to be precise, does so from the named field @field
+ * within the structure @node.
  *
- * Return value: Returns SHISHI_OK iff successful.
+ * Return value: Returns %SHISHI_OK if successful, or an error..
  **/
 int
 shishi_time (Shishi * handle, Shishi_asn1 node, const char *field, char **t)
@@ -130,17 +136,19 @@ shishi_time (Shishi * handle, Shishi_asn1 node, const 
char *field, char **t)
 
 /**
  * shishi_ctime:
- * @handle: shishi handle as allocated by shishi_init().
- * @node: ASN.1 variable to read field from.
- * @field: name of field in @node to read.
- * @t: pointer to time field to set.
+ * @handle: Shishi handle as allocated by shishi_init().
+ * @node: ASN.1 structure to read field from.
+ * @field: Name of field in @node to read.
+ * @t: Pointer to a C-time valued integer, being updated with
+ *   the time value to be extracted.
  *
- * Extract time from ASN.1 structure.
+ * Extracts time information from an ASN.1 structure @node,
+ * and from an arbitrary element @field of that structure.
  *
- * Return value: Returns SHISHI_OK if successful,
- *   SHISHI_ASN1_NO_ELEMENT if the element do not exist,
- *   SHISHI_ASN1_NO_VALUE if the field has no value, ot
- *   SHISHI_ASN1_ERROR otherwise.
+ * Return value: Returns %SHISHI_OK if successful,
+ *   %SHISHI_ASN1_NO_ELEMENT if the element does not exist,
+ *   %SHISHI_ASN1_NO_VALUE if the field has no value.
+ *   In all other cases, %SHISHI_ASN1_ERROR is returned.
  **/
 int
 shishi_ctime (Shishi * handle, Shishi_asn1 node, const char *field,
diff --git a/lib/version.c b/lib/version.c
index 0944e33..6c48cff 100644
--- a/lib/version.c
+++ b/lib/version.c
@@ -24,14 +24,17 @@
 
 /**
  * shishi_check_version:
- * @req_version: version string to compare with, or NULL
+ * @req_version: Oldest acceptable version, or %NULL.
  *
- * Check that the version of the library is at minimum the one given
- * as a string in @req_version.
+ * Checks that the installed library version is at least
+ * as recent as the one provided in @req_version.
+ * The version string is formatted like "1.0.2".
  *
- * Return value: the actual version string of the library; NULL if the
- *   condition is not met.  If %NULL is passed to this function no
- *   check is done and only the version string is returned.
+ * Whenever %NULL is passed to this function, the check is
+ * suppressed, but the library version is still returned.
+ *
+ * Return value: Returns the active library version,
+ *   or %NULL, should the running library be too old.
  **/
 const char *
 shishi_check_version (const char *req_version)


hooks/post-receive
-- 
GNU shishi