diff --git a/include/git2/repository.h b/include/git2/repository.h
index ced5ad572..4250ae161 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -88,7 +88,6 @@ GIT_EXTERN(void) git_repository_free(git_repository *repo);
  *
  * TODO:
  *	- Reinit the repository
- *	- Create config files
  *
  * @param repo_out pointer to the repo which will be created or reinitialized
  * @param path the path to the repository
@@ -146,8 +145,43 @@ GIT_EXTERN(int) git_repository_head_orphan(git_repository *repo);
  */
 GIT_EXTERN(int) git_repository_is_empty(git_repository *repo);
 
+/**
+ * Get the path of this repository
+ *
+ * This is the path of the `.git` folder for normal repositories,
+ * or of the repository itself for bare repositories.
+ *
+ * @param repo A repository object
+ * @return the path to the repository
+ */
 GIT_EXTERN(const char *) git_repository_path(git_repository *repo);
+
+/**
+ * Get the path of the working directory for this repository
+ *
+ * If the repository is bare, this function will always return
+ * NULL.
+ *
+ * @param repo A repository object
+ * @return the path to the working dir, if it exists
+ */
 GIT_EXTERN(const char *) git_repository_workdir(git_repository *repo);
+
+/**
+ * Set the path to the working directory for this repository
+ *
+ * The working directory doesn't need to be the same one
+ * that contains the `.git` folder for this repository.
+ *
+ * If this repository is bare, setting its working directory
+ * will turn it into a normal repository, capable of performing
+ * all the common workdir operations (checkout, status, index
+ * manipulation, etc).
+ *
+ * @param repo A repository object
+ * @param workdir The path to a working directory
+ * @return GIT_SUCCESS, or an error code
+ */
 GIT_EXTERN(int) git_repository_set_workdir(git_repository *repo, const char *workdir);
 
 /**
@@ -158,13 +192,97 @@ GIT_EXTERN(int) git_repository_set_workdir(git_repository *repo, const char *wor
  */
 GIT_EXTERN(int) git_repository_is_bare(git_repository *repo);
 
+/**
+ * Get the configuration file for this repository.
+ *
+ * If a configuration file has not been set, the default
+ * config set for the repository will be returned, including
+ * global and system configurations (if they are available).
+ *
+ * The configuration file must be freed once it's no longer
+ * being used by the user.
+ *
+ * @param out Pointer to store the loaded config file
+ * @param repo A repository object
+ * @return GIT_SUCCESS, or an error code
+ */
 GIT_EXTERN(int) git_repository_config(git_config **out, git_repository *repo);
+
+/**
+ * Set the configuration file for this repository
+ *
+ * This configuration file will be used for all configuration
+ * queries involving this repository.
+ *
+ * The repository will keep a reference to the config file;
+ * the user must still free the config after setting it
+ * to the repository, or it will leak.
+ *
+ * @param repo A repository object
+ * @param config A Config object
+ */
 GIT_EXTERN(void) git_repository_set_config(git_repository *repo, git_config *config);
 
+/**
+ * Get the Object Database for this repository.
+ *
+ * If a custom ODB has not been set, the default
+ * database for the repository will be returned (the one
+ * located in `.git/objects`).
+ *
+ * The ODB must be freed once it's no longer being used by
+ * the user.
+ *
+ * @param out Pointer to store the loaded ODB
+ * @param repo A repository object
+ * @return GIT_SUCCESS, or an error code
+ */
 GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo);
+
+/**
+ * Set the Object Database for this repository
+ *
+ * The ODB will be used for all object-related operations
+ * involving this repository.
+ *
+ * The repository will keep a reference to the ODB; the user
+ * must still free the ODB object after setting it to the
+ * repository, or it will leak.
+ *
+ * @param repo A repository object
+ * @param odb An ODB object
+ */
 GIT_EXTERN(void) git_repository_set_odb(git_repository *repo, git_odb *odb);
 
+/**
+ * Get the Index file for this repository.
+ *
+ * If a custom index has not been set, the default
+ * index for the repository will be returned (the one
+ * located in `.git/index`).
+ *
+ * The index must be freed once it's no longer being used by
+ * the user.
+ *
+ * @param out Pointer to store the loaded index
+ * @param repo A repository object
+ * @return GIT_SUCCESS, or an error code
+ */
 GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo);
+
+/**
+ * Set the index file for this repository
+ *
+ * This index will be used for all index-related operations
+ * involving this repository.
+ *
+ * The repository will keep a reference to the index file;
+ * the user must still free the index after setting it
+ * to the repository, or it will leak.
+ *
+ * @param repo A repository object
+ * @param index An index object
+ */
 GIT_EXTERN(void) git_repository_set_index(git_repository *repo, git_index *index);
 
 /** @} */