Merge pull request #4954 from tiennou/fix/documentation

Documentation fixes

5 files changed, 142 insertions, 89 deletions

diff --git a/docs/error-handling.md b/docs/error-handling.md
index 8df9a4074..05725f2ed 100644
--- a/docs/error-handling.md
+++ b/docs/error-handling.md
@@ -110,6 +110,15 @@ int git_repository_open(git_repository **repository, const char *path)
 }
 ~~~
 
+Note that some error codes have been defined with a specific meaning in the
+context of callbacks:
+- `GIT_EUSER` provides a way to bubble up a non libgit2-related failure, which
+  allows it to be preserved all the way up to the initial function call (a `git_cred`
+  setup trying to access an unavailable LDAP server for instance).
+- `GIT_EPASSTHROUGH` provides a way to tell libgit2 that it should behave as if
+  no callback was provided. This is of special interest to bindings, which would
+  always provide a C function as a "trampoline", and decide at runtime what to do.
+
 The public error API
 --------------------
 
@@ -119,7 +128,7 @@ The public error API
   of error and the error message that was generated by the library.
   Do not use this function unless the prior call to a libgit2 API
   returned an error, as it can otherwise give misleading results.
-  libgit2's error strings are not cleared aggressively, 
+  libgit2's error strings are not cleared aggressively,
   and this function may return an error string that reflects a prior error,
   possibly even reflecting internal state.
 
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 0386916d2..04c7300ce 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -94,40 +94,53 @@ GIT_EXTERN(int) git_repository_discover(
 
 /**
  * Option flags for `git_repository_open_ext`.
- *
- * * GIT_REPOSITORY_OPEN_NO_SEARCH - Only open the repository if it can be
- *   immediately found in the start_path.  Do not walk up from the
- *   start_path looking at parent directories.
- * * GIT_REPOSITORY_OPEN_CROSS_FS - Unless this flag is set, open will not
- *   continue searching across filesystem boundaries (i.e. when `st_dev`
- *   changes from the `stat` system call).  (E.g. Searching in a user's home
- *   directory "/home/user/source/" will not return "/.git/" as the found
- *   repo if "/" is a different filesystem than "/home".)
- * * GIT_REPOSITORY_OPEN_BARE - Open repository as a bare repo regardless
- *   of core.bare config, and defer loading config file for faster setup.
- *   Unlike `git_repository_open_bare`, this can follow gitlinks.
- * * GIT_REPOSITORY_OPEN_NO_DOTGIT - Do not check for a repository by
- *   appending /.git to the start_path; only open the repository if
- *   start_path itself points to the git directory.
- * * GIT_REPOSITORY_OPEN_FROM_ENV - Find and open a git repository,
- *   respecting the environment variables used by the git command-line
- *   tools. If set, `git_repository_open_ext` will ignore the other
- *   flags and the `ceiling_dirs` argument, and will allow a NULL `path`
- *   to use `GIT_DIR` or search from the current directory. The search
- *   for a repository will respect $GIT_CEILING_DIRECTORIES and
- *   $GIT_DISCOVERY_ACROSS_FILESYSTEM.  The opened repository will
- *   respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and
- *   $GIT_ALTERNATE_OBJECT_DIRECTORIES.  In the future, this flag will
- *   also cause `git_repository_open_ext` to respect $GIT_WORK_TREE and
- *   $GIT_COMMON_DIR; currently, `git_repository_open_ext` with this
- *   flag will error out if either $GIT_WORK_TREE or $GIT_COMMON_DIR is
- *   set.
  */
 typedef enum {
+	/**
+	 * Only open the repository if it can be immediately found in the
+	 * start_path. Do not walk up from the start_path looking at parent
+	 * directories.
+	 */
 	GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0),
+
+	/**
+	 * Unless this flag is set, open will not continue searching across
+	 * filesystem boundaries (i.e. when `st_dev` changes from the `stat`
+	 * system call).  For example, searching in a user's home directory at
+	 * "/home/user/source/" will not return "/.git/" as the found repo if
+	 * "/" is a different filesystem than "/home".
+	 */
 	GIT_REPOSITORY_OPEN_CROSS_FS  = (1 << 1),
+
+	/**
+	 * Open repository as a bare repo regardless of core.bare config, and
+	 * defer loading config file for faster setup.
+	 * Unlike `git_repository_open_bare`, this can follow gitlinks.
+	 */
 	GIT_REPOSITORY_OPEN_BARE      = (1 << 2),
+
+	/**
+	 * Do not check for a repository by appending /.git to the start_path;
+	 * only open the repository if start_path itself points to the git
+	 * directory.
+	 */
 	GIT_REPOSITORY_OPEN_NO_DOTGIT = (1 << 3),
+
+	/**
+	 * Find and open a git repository, respecting the environment variables
+	 * used by the git command-line tools.
+	 * If set, `git_repository_open_ext` will ignore the other flags and
+	 * the `ceiling_dirs` argument, and will allow a NULL `path` to use
+	 * `GIT_DIR` or search from the current directory.
+	 * The search for a repository will respect $GIT_CEILING_DIRECTORIES and
+	 * $GIT_DISCOVERY_ACROSS_FILESYSTEM.  The opened repository will
+	 * respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and
+	 * $GIT_ALTERNATE_OBJECT_DIRECTORIES.
+	 * In the future, this flag will also cause `git_repository_open_ext`
+	 * to respect $GIT_WORK_TREE and $GIT_COMMON_DIR; currently,
+	 * `git_repository_open_ext` with this flag will error out if either
+	 * $GIT_WORK_TREE or $GIT_COMMON_DIR is set.
+	 */
 	GIT_REPOSITORY_OPEN_FROM_ENV  = (1 << 4),
 } git_repository_open_flag_t;
 
diff --git a/include/git2/signature.h b/include/git2/signature.h
index 7a2a0238a..b14f3ea89 100644
--- a/include/git2/signature.h
+++ b/include/git2/signature.h
@@ -30,8 +30,8 @@ GIT_BEGIN_DECL
  * @param out new signature, in case of error NULL
  * @param name name of the person
  * @param email email of the person
- * @param time time when the action happened
- * @param offset timezone offset in minutes for the time
+ * @param time time (in seconds from epoch) when the action happened
+ * @param offset timezone offset (in minutes) for the time
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset);
diff --git a/include/git2/sys/transport.h b/include/git2/sys/transport.h
index 92cb32b17..bba8feafe 100644
--- a/include/git2/sys/transport.h
+++ b/include/git2/sys/transport.h
@@ -33,8 +33,9 @@ typedef enum {
 } git_transport_flags_t;
 
 struct git_transport {
-	unsigned int version;
-	/* Set progress and error callbacks */
+	unsigned int version; /**< The struct version */
+
+	/** Set progress and error callbacks */
 	int GIT_CALLBACK(set_callbacks)(
 		git_transport *transport,
 		git_transport_message_cb progress_cb,
@@ -42,13 +43,15 @@ struct git_transport {
 		git_transport_certificate_check_cb certificate_check_cb,
 		void *payload);
 
-	/* Set custom headers for HTTP requests */
+	/** Set custom headers for HTTP requests */
 	int GIT_CALLBACK(set_custom_headers)(
 		git_transport *transport,
 		const git_strarray *custom_headers);
 
-	/* Connect the transport to the remote repository, using the given
-	 * direction. */
+	/**
+	 * Connect the transport to the remote repository, using the given
+	 * direction.
+	 */
 	int GIT_CALLBACK(connect)(
 		git_transport *transport,
 		const char *url,
@@ -58,29 +61,40 @@ struct git_transport {
 		int direction,
 		int flags);
 
-	/* This function may be called after a successful call to
-	 * connect(). The array returned is owned by the transport and
-	 * is guaranteed until the next call of a transport function. */
+	/**
+	 * Get the list of available references in the remote repository.
+	 *
+	 * This function may be called after a successful call to
+	 * `connect()`. The array returned is owned by the transport and
+	 * must be kept valid until the next call to one of its functions.
+	 */
 	int GIT_CALLBACK(ls)(
 		const git_remote_head ***out,
 		size_t *size,
 		git_transport *transport);
 
-	/* Executes the push whose context is in the git_push object. */
+	/** Executes the push whose context is in the git_push object. */
 	int GIT_CALLBACK(push)(git_transport *transport, git_push *push, const git_remote_callbacks *callbacks);
 
-	/* This function may be called after a successful call to connect(), when
-	 * the direction is FETCH. The function performs a negotiation to calculate
-	 * the wants list for the fetch. */
+	/**
+	 * Negotiate a fetch with the remote repository.
+	 *
+	 * This function may be called after a successful call to `connect()`,
+	 * when the direction is GIT_DIRECTION_FETCH. The function performs a
+	 * negotiation to calculate the `wants` list for the fetch.
+	 */
 	int GIT_CALLBACK(negotiate_fetch)(
 		git_transport *transport,
 		git_repository *repo,
 		const git_remote_head * const *refs,
 		size_t count);
 
-	/* This function may be called after a successful call to negotiate_fetch(),
-	 * when the direction is FETCH. This function retrieves the pack file for
-	 * the fetch from the remote end. */
+	/**
+	 * Start downloading the packfile from the remote repository.
+	 *
+	 * This function may be called after a successful call to
+	 * negotiate_fetch(), when the direction is GIT_DIRECTION_FETCH.
+	 */
 	int GIT_CALLBACK(download_pack)(
 		git_transport *transport,
 		git_repository *repo,
@@ -88,20 +102,24 @@ struct git_transport {
 		git_transfer_progress_cb progress_cb,
 		void *progress_payload);
 
-	/* Checks to see if the transport is connected */
+	/** Checks to see if the transport is connected */
 	int GIT_CALLBACK(is_connected)(git_transport *transport);
 
-	/* Reads the flags value previously passed into connect() */
+	/** Reads the flags value previously passed into connect() */
 	int GIT_CALLBACK(read_flags)(git_transport *transport, int *flags);
 
-	/* Cancels any outstanding transport operation */
+	/** Cancels any outstanding transport operation */
 	void GIT_CALLBACK(cancel)(git_transport *transport);
 
-	/* This function is the reverse of connect() -- it terminates the
-	 * connection to the remote end. */
+	/**
+	 * Close the connection to the remote repository.
+	 *
+	 * This function is the reverse of connect() -- it terminates the
+	 * connection to the remote end.
+	 */
 	int GIT_CALLBACK(close)(git_transport *transport);
 
-	/* Frees/destructs the git_transport object. */
+	/** Frees/destructs the git_transport object. */
 	void GIT_CALLBACK(free)(git_transport *transport);
 };
 
@@ -167,10 +185,13 @@ GIT_EXTERN(int) git_transport_register(
 	void *param);
 
 /**
- *
  * Unregister a custom transport definition which was previously registered
  * with git_transport_register.
  *
+ * The caller is responsible for synchronizing calls to git_transport_register
+ * and git_transport_unregister with other calls to the library that
+ * instantiate transports.
+ *
  * @param prefix From the previous call to git_transport_register
  * @return 0 or an error code
  */
@@ -262,20 +283,7 @@ GIT_EXTERN(int) git_transport_smart_proxy_options(git_proxy_options *out, git_tr
  *** Begin interface for subtransports for the smart transport ***
  */
 
-/* The smart transport knows how to speak the git protocol, but it has no
- * knowledge of how to establish a connection between it and another endpoint,
- * or how to move data back and forth. For this, a subtransport interface is
- * declared, and the smart transport delegates this work to the subtransports.
- * Three subtransports are implemented: git, http, and winhttp. (The http and
- * winhttp transports each implement both http and https.) */
-
-/* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1
- * (request/response). The smart transport handles the differences in its own
- * logic. The git subtransport is RPC = 0, while http and winhttp are both
- * RPC = 1. */
-
-/* Actions that the smart transport can ask
- * a subtransport to perform */
+/** Actions that the smart transport can ask a subtransport to perform */
 typedef enum {
 	GIT_SERVICE_UPLOADPACK_LS = 1,
 	GIT_SERVICE_UPLOADPACK = 2,
@@ -286,58 +294,81 @@ typedef enum {
 typedef struct git_smart_subtransport git_smart_subtransport;
 typedef struct git_smart_subtransport_stream git_smart_subtransport_stream;
 
-/* A stream used by the smart transport to read and write data
+/**
+ * A stream used by the smart transport to read and write data
  * from a subtransport */
 struct git_smart_subtransport_stream {
-	/* The owning subtransport */
+	/** The owning subtransport */
 	git_smart_subtransport *subtransport;
 
+	/** Read available data from the stream */
 	int GIT_CALLBACK(read)(
 		git_smart_subtransport_stream *stream,
 		char *buffer,
 		size_t buf_size,
 		size_t *bytes_read);
 
+	/** Write data to the stream */
 	int GIT_CALLBACK(write)(
 		git_smart_subtransport_stream *stream,
 		const char *buffer,
 		size_t len);
 
+	/** Free the stream */
 	void GIT_CALLBACK(free)(
 		git_smart_subtransport_stream *stream);
 };
 
-/* An implementation of a subtransport which carries data for the
+/**
+ * An implementation of a subtransport which carries data for the
  * smart transport */
 struct git_smart_subtransport {
+	/**
+	 * Setup a subtransport stream for the requested action.
+	 */
 	int GIT_CALLBACK(action)(
 			git_smart_subtransport_stream **out,
 			git_smart_subtransport *transport,
 			const char *url,
 			git_smart_service_t action);
 
-	/* Subtransports are guaranteed a call to close() between
+	/**
+	 * Close the subtransport.
+	 *
+	 * Subtransports are guaranteed a call to close() between
 	 * calls to action(), except for the following two "natural" progressions
-	 * of actions against a constant URL.
+	 * of actions against a constant URL:
 	 *
-	 * 1. UPLOADPACK_LS -> UPLOADPACK
-	 * 2. RECEIVEPACK_LS -> RECEIVEPACK */
+	 * - UPLOADPACK_LS -> UPLOADPACK
+	 * - RECEIVEPACK_LS -> RECEIVEPACK
+	 */
 	int GIT_CALLBACK(close)(git_smart_subtransport *transport);
 
+	/** Free the subtransport */
 	void GIT_CALLBACK(free)(git_smart_subtransport *transport);
 };
 
-/* A function which creates a new subtransport for the smart transport */
+/** A function which creates a new subtransport for the smart transport */
 typedef int GIT_CALLBACK(git_smart_subtransport_cb)(
 	git_smart_subtransport **out,
-	git_transport* owner,
-	void* param);
+	git_transport *owner,
+	void *param);
 
 /**
  * Definition for a "subtransport"
  *
- * This is used to let the smart protocol code know about the protocol
- * which you are implementing.
+ * The smart transport knows how to speak the git protocol, but it has no
+ * knowledge of how to establish a connection between it and another endpoint,
+ * or how to move data back and forth. For this, a subtransport interface is
+ * declared, and the smart transport delegates this work to the subtransports.
+ *
+ * Three subtransports are provided by libgit2: git, http, and winhttp.
+ * The http and winhttp transports each implement both http and https.
+ *
+ * Subtransports can either be RPC = 0 (persistent connection) or RPC = 1
+ * (request/response). The smart transport handles the differences in its own
+ * logic. The git subtransport is RPC = 0, while http and winhttp are both
+ * RPC = 1.
  */
 typedef struct git_smart_subtransport_definition {
 	/** The function to use to create the git_smart_subtransport */
@@ -349,17 +380,17 @@ typedef struct git_smart_subtransport_definition {
 	 */
 	unsigned rpc;
 
-	/** Param of the callback
-	 */
-	void* param;
+	/** User-specified parameter passed to the callback */
+	void *param;
 } git_smart_subtransport_definition;
 
 /* Smart transport subtransports that come with libgit2 */
 
 /**
- * Create an instance of the http subtransport. This subtransport
- * also supports https. On Win32, this subtransport may be implemented
- * using the WinHTTP library.
+ * Create an instance of the http subtransport.
+ *
+ * This subtransport also supports https. On Win32, this subtransport may be
+ * implemented using the WinHTTP library.
  *
  * @param out The newly created subtransport
  * @param owner The smart transport to own this subtransport
@@ -367,7 +398,7 @@ typedef struct git_smart_subtransport_definition {
  */
 GIT_EXTERN(int) git_smart_subtransport_http(
 	git_smart_subtransport **out,
-	git_transport* owner,
+	git_transport *owner,
 	void *param);
 
 /**
@@ -379,7 +410,7 @@ GIT_EXTERN(int) git_smart_subtransport_http(
  */
 GIT_EXTERN(int) git_smart_subtransport_git(
 	git_smart_subtransport **out,
-	git_transport* owner,
+	git_transport *owner,
 	void *param);
 
 /**
@@ -391,7 +422,7 @@ GIT_EXTERN(int) git_smart_subtransport_git(
  */
 GIT_EXTERN(int) git_smart_subtransport_ssh(
 	git_smart_subtransport **out,
-	git_transport* owner,
+	git_transport *owner,
 	void *param);
 
 /** @} */
diff --git a/include/git2/types.h b/include/git2/types.h
index 6c57ed0af..0eaa0041d 100644
--- a/include/git2/types.h
+++ b/include/git2/types.h
@@ -59,7 +59,7 @@ typedef __haiku_std_int64 git_time_t;
  * app, even though /we/ define _FILE_OFFSET_BITS=64.
  */
 typedef int64_t git_off_t;
-typedef int64_t git_time_t;
+typedef int64_t git_time_t; /**< time in seconds from epoch */
 
 #endif