[Pkg-gnupg-commit] [gnupg2] 08/166: tools: Add comments explaining the functions parameters.

[Daniel Kahn Gillmor]

This is an automated email from the git hooks/post-receive script.

dkg pushed a commit to branch experimental
in repository gnupg2.

commit 82e309ad06884e54693f4856412984331febdda0
Author: Justus Winter <justus at g10code.com>
Date:   Tue Jan 24 12:57:43 2017 +0100

    tools: Add comments explaining the functions parameters.
    
    * tools/gpgconf-comp.c (change_options_file): Add comments explaining
    the functions parameters.
    (change_options_program): Likewise.
    --
    From reading those two functions it is not clear why we write the new
    configuration to the source file, and read the current configuration
    from the destination file.  The identifiers are named for the benefit
    of the callee.
    
    Note that identifiers that require that much explanation are poorly
    chosen.
    
    Signed-off-by: Justus Winter <justus at g10code.com>
---
 tools/gpgconf-comp.c | 29 +++++++++++++++++++++++++++--
 1 file changed, 27 insertions(+), 2 deletions(-)

diff --git a/tools/gpgconf-comp.c b/tools/gpgconf-comp.c
index 180fd65..641738e 100644
--- a/tools/gpgconf-comp.c
+++ b/tools/gpgconf-comp.c
@@ -2573,7 +2573,20 @@ copy_file (const char *src_name, const char *dst_name)
 
 
 /* Create and verify the new configuration file for the specified
-   backend and component.  Returns 0 on success and -1 on error.  */
+ * backend and component.  Returns 0 on success and -1 on error.  This
+ * function may store pointers to malloced strings in SRC_FILENAMEP,
+ * DEST_FILENAMEP, and ORIG_FILENAMEP.  Those must be freed by the
+ * caller.  The strings refer to three versions of the configuration
+ * file:
+ *
+ * SRC_FILENAME:  The updated configuration is written to this file.
+ * DEST_FILENAME: Name of the configuration file read by the
+ *                component.
+ * ORIG_FILENAME: A backup of the previous configuration file.
+ *
+ * To apply the configuration change, rename SRC_FILENAME to
+ * DEST_FILENAME.  To revert to the previous configuration, rename
+ * ORIG_FILENAME to DEST_FILENAME.  */
 static int
 change_options_file (gc_component_t component, gc_backend_t backend,
 		     char **src_filenamep, char **dest_filenamep,
@@ -2882,7 +2895,19 @@ change_options_file (gc_component_t component, gc_backend_t backend,
 
 /* Create and verify the new configuration file for the specified
  * backend and component.  Returns 0 on success and -1 on error.  If
- * VERBATIM is set the profile mode is used. */
+ * VERBATIM is set the profile mode is used.  This function may store
+ * pointers to malloced strings in SRC_FILENAMEP, DEST_FILENAMEP, and
+ * ORIG_FILENAMEP.  Those must be freed by the caller.  The strings
+ * refer to three versions of the configuration file:
+ *
+ * SRC_FILENAME:  The updated configuration is written to this file.
+ * DEST_FILENAME: Name of the configuration file read by the
+ *                component.
+ * ORIG_FILENAME: A backup of the previous configuration file.
+ *
+ * To apply the configuration change, rename SRC_FILENAME to
+ * DEST_FILENAME.  To revert to the previous configuration, rename
+ * ORIG_FILENAME to DEST_FILENAME.  */
 static int
 change_options_program (gc_component_t component, gc_backend_t backend,
 			char **src_filenamep, char **dest_filenamep,

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gnupg2.git