Commit a2a305fcf4a4c1a5026fa29a94062fe2069d1059
2011-06-07T15:39:40
config: explain the cfg and file relationship better 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>
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
diff --git a/include/git2/config.h b/include/git2/config.h
index fca9d9d..4167bf8 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
*/