From a2a305fcf4a4c1a5026fa29a94062fe2069d1059 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= <cmn@elego.de>
Date: Tue, 7 Jun 2011 15:39:40 +0200
Subject: [PATCH] config: explain the cfg and file relationship better
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

It's not clear how git_config and git_config_file relate to one
another. Be more explicit about their relationship in the function
documentation.

Signed-off-by: Carlos Martín Nieto <cmn@elego.de>
---
 include/git2/config.h | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/include/git2/config.h b/include/git2/config.h
index fca9d9dc4..4167bf8e5 100644
--- a/include/git2/config.h
+++ b/include/git2/config.h
@@ -56,7 +56,9 @@ struct git_config_file {
  * Create a configuration file backend for ondisk files
  *
  * These are the normal `.gitconfig` files that Core Git
- * processes.
+ * processes. Note that you first have to add this file to a
+ * configuration object before you can query it for configuration
+ * variables.
  *
  * @param out the new backend
  * @path where the config file is located
@@ -64,13 +66,21 @@ struct git_config_file {
 GIT_EXTERN(int) git_config_file__ondisk(struct git_config_file **out, const char *path);
 
 /**
- * Allocate a new configuration
+ * Allocate a new configuration object
+ *
+ * This object is empty, so you have to add a file to it before you
+ * can do anything with it.
+ *
+ * @param out pointer to the new configuration
  */
 GIT_EXTERN(int) git_config_new(git_config **out);
 
 /**
  * Open a configuration file
  *
+ * This creates a new configuration object and adds the specified file
+ * to it.
+ *
  * @param cfg_out pointer to the configuration data
  * @param path where to load the confiration from
  */
@@ -86,17 +96,17 @@ GIT_EXTERN(int) git_config_open_global(git_config **cfg);
 /**
  * Add a config backend to an existing instance
  *
- * Note that the configuration will call the backend's ->free()
- * function.
+ * Note that the configuration object will free the file
+ * automatically.
  *
  * @param cfg the configuration to add the file to
- * @param file the configuration source (file) to add
+ * @param file the configuration file (backend) to add
  * @param priority the priority the backend should have
  */
 GIT_EXTERN(int) git_config_add_file(git_config *cfg, git_config_file *file, int priority);
 
 /**
- * Free the configuration and its associated memory
+ * Free the configuration and its associated memory and files
  *
  * @param cfg the configuration to free
  */