rugged 1.6.3 → 1.9.0

data/vendor/libgit2/include/git2/sys/refdb_backend.h

@@ -12,9 +12,9 @@
 #include "git2/oid.h"
 
 /**
- * @file git2/refdb_backend.h
- * @brief Git custom refs backend functions
- * @defgroup git_refdb_backend Git custom refs backend API
+ * @file git2/sys/refdb_backend.h
+ * @brief Custom reference database backends for refs storage
+ * @defgroup git_refdb_backend Custom reference database backends for refs storage
  * @ingroup Git
  * @{
  */
@@ -65,9 +65,9 @@ struct git_refdb_backend {
 	 *
 	 * A refdb implementation must provide this function.
 	 *
-	 * @arg exists The implementation shall set this to `0` if a ref does
+	 * @param exists The implementation shall set this to `0` if a ref does
 	 *             not exist, otherwise to `1`.
-	 * @arg ref_name The reference's name that should be checked for
+	 * @param ref_name The reference's name that should be checked for
 	 *               existence.
 	 * @return `0` on success, a negative error value code.
 	 */
@@ -81,9 +81,9 @@ struct git_refdb_backend {
 	 *
 	 * A refdb implementation must provide this function.
 	 *
-	 * @arg out The implementation shall set this to the allocated
+	 * @param out The implementation shall set this to the allocated
 	 *          reference, if it could be found, otherwise to `NULL`.
-	 * @arg ref_name The reference's name that should be checked for
+	 * @param ref_name The reference's name that should be checked for
 	 *               existence.
 	 * @return `0` on success, `GIT_ENOTFOUND` if the reference does
 	 *         exist, otherwise a negative error code.
@@ -98,12 +98,12 @@ struct git_refdb_backend {
 	 *
 	 * A refdb implementation must provide this function.
 	 *
-	 * @arg out The implementation shall set this to the allocated
+	 * @param out The implementation shall set this to the allocated
 	 *          reference iterator. A custom structure may be used with an
 	 *          embedded `git_reference_iterator` structure. Both `next`
 	 *          and `next_name` functions of `git_reference_iterator` need
 	 *          to be populated.
-	 * @arg glob A pattern to filter references by. If given, the iterator
+	 * @param glob A pattern to filter references by. If given, the iterator
 	 *           shall only return references that match the glob when
 	 *           passed to `wildmatch`.
 	 * @return `0` on success, otherwise a negative error code.
@@ -118,20 +118,20 @@ struct git_refdb_backend {
 	 *
 	 * A refdb implementation must provide this function.
 	 *
-	 * @arg ref The reference to persist. May either be a symbolic or
+	 * @param ref The reference to persist. May either be a symbolic or
 	 *          direct reference.
-	 * @arg force Whether to write the reference if a reference with the
+	 * @param force Whether to write the reference if a reference with the
 	 *            same name already exists.
-	 * @arg who The person updating the reference. Shall be used to create
+	 * @param who The person updating the reference. Shall be used to create
 	 *          a reflog entry.
-	 * @arg message The message detailing what kind of reference update is
+	 * @param message The message detailing what kind of reference update is
 	 *              performed. Shall be used to create a reflog entry.
-	 * @arg old If not `NULL` and `force` is not set, then the
+	 * @param old If not `NULL` and `force` is not set, then the
 	 *          implementation needs to ensure that the reference is currently at
 	 *          the given OID before writing the new value. If both `old`
 	 *          and `old_target` are `NULL`, then the reference should not
 	 *          exist at the point of writing.
-	 * @arg old_target If not `NULL` and `force` is not set, then the
+	 * @param old_target If not `NULL` and `force` is not set, then the
 	 *                 implementation needs to ensure that the symbolic
 	 *                 reference is currently at the given target before
 	 *                 writing the new value. If both `old` and
@@ -149,15 +149,15 @@ struct git_refdb_backend {
 	 *
 	 * A refdb implementation must provide this function.
 	 *
-	 * @arg out The implementation shall set this to the newly created
+	 * @param out The implementation shall set this to the newly created
 	 *          reference or `NULL` on error.
-	 * @arg old_name The current name of the reference that is to be renamed.
-	 * @arg new_name The new name that the old reference shall be renamed to.
-	 * @arg force Whether to write the reference if a reference with the
+	 * @param old_name The current name of the reference that is to be renamed.
+	 * @param new_name The new name that the old reference shall be renamed to.
+	 * @param force Whether to write the reference if a reference with the
 	 *            target name already exists.
-	 * @arg who The person updating the reference. Shall be used to create
+	 * @param who The person updating the reference. Shall be used to create
 	 *          a reflog entry.
-	 * @arg message The message detailing what kind of reference update is
+	 * @param message The message detailing what kind of reference update is
 	 *              performed. Shall be used to create a reflog entry.
 	 * @return `0` on success, otherwise a negative error code.
 	 */
@@ -173,11 +173,11 @@ struct git_refdb_backend {
 	 *
 	 * A refdb implementation must provide this function.
 	 *
-	 * @arg ref_name The name of the reference name that shall be deleted.
-	 * @arg old_id If not `NULL` and `force` is not set, then the
+	 * @param ref_name The name of the reference name that shall be deleted.
+	 * @param old_id If not `NULL` and `force` is not set, then the
 	 *             implementation needs to ensure that the reference is currently at
 	 *             the given OID before writing the new value.
-	 * @arg old_target If not `NULL` and `force` is not set, then the
+	 * @param old_target If not `NULL` and `force` is not set, then the
 	 *                 implementation needs to ensure that the symbolic
 	 *                 reference is currently at the given target before
 	 *                 writing the new value.
@@ -243,7 +243,7 @@ struct git_refdb_backend {
 	 *
 	 * A refdb implementation must provide this function.
 	 *
-	 * @arg reflog The complete reference log for a given reference. Note
+	 * @param reflog The complete reference log for a given reference. Note
 	 *             that this may contain entries that have already been
 	 *             written to disk.
 	 * @return `0` on success, a negative error code otherwise
@@ -255,8 +255,8 @@ struct git_refdb_backend {
 	 *
 	 * A refdb implementation must provide this function.
 	 *
-	 * @arg old_name The name of old reference whose reflog shall be renamed from.
-	 * @arg new_name The name of new reference whose reflog shall be renamed to.
+	 * @param old_name The name of old reference whose reflog shall be renamed from.
+	 * @param new_name The name of new reference whose reflog shall be renamed to.
 	 * @return `0` on success, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(reflog_rename)(git_refdb_backend *_backend, const char *old_name, const char *new_name);
@@ -266,7 +266,7 @@ struct git_refdb_backend {
 	 *
 	 * A refdb implementation must provide this function.
 	 *
-	 * @arg name The name of the reference whose reflog shall be deleted.
+	 * @param name The name of the reference whose reflog shall be deleted.
 	 * @return `0` on success, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(reflog_delete)(git_refdb_backend *backend, const char *name);
@@ -277,9 +277,9 @@ struct git_refdb_backend {
 	 * A refdb implementation may provide this function; if it is not
 	 * provided, the transaction API will fail to work.
 	 *
-	 * @arg payload_out Opaque parameter that will be passed verbosely to
+	 * @param payload_out Opaque parameter that will be passed verbosely to
 	 *                  `unlock`.
-	 * @arg refname Reference that shall be locked.
+	 * @param refname Reference that shall be locked.
 	 * @return `0` on success, a negative error code otherwise
 	 */
 	int GIT_CALLBACK(lock)(void **payload_out, git_refdb_backend *backend, const char *refname);
@@ -294,16 +294,16 @@ struct git_refdb_backend {
 	 * A refdb implementation must provide this function if a `lock`
 	 * implementation is provided.
 	 *
-	 * @arg payload The payload returned by `lock`.
-	 * @arg success `1` if a reference should be updated, `2` if
+	 * @param payload The payload returned by `lock`.
+	 * @param success `1` if a reference should be updated, `2` if
 	 *              a reference should be deleted, `0` if the lock must be
 	 *              discarded.
-	 * @arg update_reflog `1` in case the reflog should be updated, `0`
+	 * @param update_reflog `1` in case the reflog should be updated, `0`
 	 *                    otherwise.
-	 * @arg ref The reference which should be unlocked.
-	 * @arg who The person updating the reference. Shall be used to create
+	 * @param ref The reference which should be unlocked.
+	 * @param who The person updating the reference. Shall be used to create
 	 *          a reflog entry in case `update_reflog` is set.
-	 * @arg message The message detailing what kind of reference update is
+	 * @param message The message detailing what kind of reference update is
 	 *              performed. Shall be used to create a reflog entry in
 	 *              case `update_reflog` is set.
 	 * @return `0` on success, a negative error code otherwise
@@ -312,7 +312,10 @@ struct git_refdb_backend {
 		      const git_reference *ref, const git_signature *sig, const char *message);
 };
 
+/** Current version for the `git_refdb_backend_options` structure */
 #define GIT_REFDB_BACKEND_VERSION 1
+
+/** Static constructor for `git_refdb_backend_options` */
 #define GIT_REFDB_BACKEND_INIT {GIT_REFDB_BACKEND_VERSION}
 
 /**
@@ -356,6 +359,7 @@ GIT_EXTERN(int) git_refdb_set_backend(
 	git_refdb *refdb,
 	git_refdb_backend *backend);
 
+/** @} */
 GIT_END_DECL
 
 #endif

data/vendor/libgit2/include/git2/sys/refs.h

@@ -13,8 +13,8 @@
 
 /**
  * @file git2/sys/refs.h
- * @brief Low-level Git ref creation
- * @defgroup git_backend Git custom backend APIs
+ * @brief Low-level git reference creation
+ * @defgroup git_backend Low-level git reference creation
  * @ingroup Git
  * @{
  */
@@ -46,4 +46,5 @@ GIT_EXTERN(git_reference *) git_reference__alloc_symbolic(
 
 /** @} */
 GIT_END_DECL
+
 #endif

data/vendor/libgit2/include/git2/sys/remote.h

@@ -13,19 +13,25 @@
 /**
  * @file git2/sys/remote.h
  * @brief Low-level remote functionality for custom transports
- * @defgroup git_remote Low-level remote functionality
+ * @defgroup git_remote Low-level remote functionality for custom transports
  * @ingroup Git
  * @{
 */
 
 GIT_BEGIN_DECL
 
+/**
+ * A remote's capabilities.
+ */
 typedef enum {
 	/** Remote supports fetching an advertised object by ID. */
 	GIT_REMOTE_CAPABILITY_TIP_OID = (1 << 0),
 
 	/** Remote supports fetching an individual reachable object. */
 	GIT_REMOTE_CAPABILITY_REACHABLE_OID = (1 << 1),
+
+	/** Remote supports push options. */
+	GIT_REMOTE_CAPABILITY_PUSH_OPTIONS = (1 << 2),
 } git_remote_capability_t;
 
 /**
@@ -43,4 +49,5 @@ GIT_EXTERN(void) git_remote_connect_options_dispose(
 
 /** @} */
 GIT_END_DECL
+
 #endif

data/vendor/libgit2/include/git2/sys/repository.h

@@ -9,16 +9,71 @@
 
 #include "git2/common.h"
 #include "git2/types.h"
+#include "git2/oid.h"
 
 /**
  * @file git2/sys/repository.h
- * @brief Git repository custom implementation routines
- * @defgroup git_backend Git custom backend APIs
+ * @brief Custom repository handling
+ * @defgroup git_repository Custom repository handling
  * @ingroup Git
  * @{
  */
 GIT_BEGIN_DECL
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+
+/**
+ * The options for creating an repository from scratch.
+ *
+ * Initialize with `GIT_REPOSITORY_NEW_OPTIONS_INIT`. Alternatively,
+ * you can use `git_repository_new_options_init`.
+ *
+ * @options[version] GIT_REPOSITORY_NEW_OPTIONS_VERSION
+ * @options[init_macro] GIT_REPOSITORY_NEW_OPTIONS_INIT
+ * @options[init_function] git_repository_new_options_init
+ */
+typedef struct git_repository_new_options {
+	unsigned int version; /**< The version */
+
+	/**
+	 * The object ID type for the object IDs that exist in the index.
+	 *
+	 * If this is not specified, this defaults to `GIT_OID_SHA1`.
+	 */
+	git_oid_t oid_type;
+} git_repository_new_options;
+
+/** Current version for the `git_repository_new_options` structure */
+#define GIT_REPOSITORY_NEW_OPTIONS_VERSION 1
+
+/** Static constructor for `git_repository_new_options` */
+#define GIT_REPOSITORY_NEW_OPTIONS_INIT { GIT_REPOSITORY_NEW_OPTIONS_VERSION }
+
+/**
+ * Initialize git_repository_new_options structure
+ *
+ * Initializes a `git_repository_new_options` with default values.
+ * Equivalent to creating an instance with
+ * `GIT_REPOSITORY_NEW_OPTIONS_INIT`.
+ *
+ * @param opts The `git_repository_new_options` struct to initialize.
+ * @param version The struct version; pass `GIT_REPOSITORY_NEW_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
+ */
+GIT_EXTERN(int) git_repository_new_options_init(
+	git_repository_new_options *opts,
+	unsigned int version);
+
+/**
+ * Create a new repository with no backends.
+ *
+ * @param[out] out The blank repository
+ * @param opts the options for repository creation, or NULL for defaults
+ * @return 0 on success, or an error code
+ */
+GIT_EXTERN(int) git_repository_new(git_repository **out, git_repository_new_options *opts);
+#else
+
 /**
  * Create a new repository with neither backends nor config object
  *
@@ -29,11 +84,13 @@ GIT_BEGIN_DECL
  * can fail to function properly: locations under $GIT_DIR, $GIT_COMMON_DIR,
  * or $GIT_INFO_DIR are impacted.
  *
- * @param out The blank repository
+ * @param[out] out The blank repository
  * @return 0 on success, or an error code
  */
 GIT_EXTERN(int) git_repository_new(git_repository **out);
 
+#endif
+
 /**
  * Reset all the internal state in a repository.
  *
@@ -156,6 +213,7 @@ GIT_EXTERN(int) git_repository_set_bare(git_repository *repo);
  * and caches them so that subsequent calls to `git_submodule_lookup` are O(1).
  *
  * @param repo the repository whose submodules will be cached.
+ * @return 0 on success, or an error code
  */
 GIT_EXTERN(int) git_repository_submodule_cache_all(
 	git_repository *repo);
@@ -171,10 +229,12 @@ GIT_EXTERN(int) git_repository_submodule_cache_all(
  * of these has changed, the cache might become invalid.
  *
  * @param repo the repository whose submodule cache will be cleared
+ * @return 0 on success, or an error code
  */
 GIT_EXTERN(int) git_repository_submodule_cache_clear(
 	git_repository *repo);
 
 /** @} */
 GIT_END_DECL
+
 #endif

data/vendor/libgit2/include/git2/sys/stream.h

@@ -11,8 +11,16 @@
 #include "git2/types.h"
 #include "git2/proxy.h"
 
+/**
+ * @file git2/sys/stream.h
+ * @brief Streaming file I/O functionality
+ * @defgroup git_stream Streaming file I/O functionality
+ * @ingroup Git
+ * @{
+ */
 GIT_BEGIN_DECL
 
+/** Current version for the `git_stream` structures */
 #define GIT_STREAM_VERSION 1
 
 /**
@@ -29,8 +37,22 @@ GIT_BEGIN_DECL
 typedef struct git_stream {
 	int version;
 
-	int encrypted;
-	int proxy_support;
+	unsigned int encrypted : 1,
+	             proxy_support : 1;
+
+	/**
+	 * Timeout for read and write operations; can be set to `0` to
+	 * block indefinitely.
+	 */
+	int timeout;
+
+	/**
+	 * Timeout to connect to the remote server; can be set to `0`
+	 * to use the system defaults. This can be shorter than the
+	 * system default - often 75 seconds - but cannot be longer.
+	 */
+	int connect_timeout;
+
 	int GIT_CALLBACK(connect)(struct git_stream *);
 	int GIT_CALLBACK(certificate)(git_cert **, struct git_stream *);
 	int GIT_CALLBACK(set_proxy)(struct git_stream *, const git_proxy_options *proxy_opts);
@@ -133,6 +155,7 @@ GIT_EXTERN(int) git_stream_register_tls(git_stream_cb ctor);
 
 #endif
 
+/**@}*/
 GIT_END_DECL
 
 #endif

data/vendor/libgit2/include/git2/sys/transport.h

@@ -9,6 +9,7 @@
 #define INCLUDE_sys_git_transport_h
 
 #include "git2/net.h"
+#include "git2/oidarray.h"
 #include "git2/proxy.h"
 #include "git2/remote.h"
 #include "git2/strarray.h"
@@ -17,14 +18,28 @@
 
 /**
  * @file git2/sys/transport.h
- * @brief Git custom transport registration interfaces and functions
- * @defgroup git_transport Git custom transport registration
+ * @brief Custom transport registration interfaces and functions
+ * @defgroup git_transport Custom transport registration
  * @ingroup Git
+ *
+ * Callers can override the default HTTPS or SSH implementation by
+ * specifying a custom transport.
  * @{
  */
 
 GIT_BEGIN_DECL
 
+/**
+ * The negotiation state during a fetch smart transport negotiation.
+ */
+typedef struct {
+	const git_remote_head * const *refs;
+	size_t refs_len;
+	git_oid *shallow_roots;
+	size_t shallow_roots_len;
+	int depth;
+} git_fetch_negotiation;
+
 struct git_transport {
 	unsigned int version; /**< The struct version */
 
@@ -96,8 +111,17 @@ struct git_transport {
 	int GIT_CALLBACK(negotiate_fetch)(
 		git_transport *transport,
 		git_repository *repo,
-		const git_remote_head * const *refs,
-		size_t count);
+		const git_fetch_negotiation *fetch_data);
+
+	/**
+	 * Return the shallow roots of the remote.
+	 *
+	 * This function may be called after a successful call to
+	 * `negotiate_fetch`.
+	 */
+	int GIT_CALLBACK(shallow_roots)(
+		git_oidarray *out,
+		git_transport *transport);
 
 	/**
 	 * Start downloading the packfile from the remote repository.
@@ -128,7 +152,10 @@ struct git_transport {
 	void GIT_CALLBACK(free)(git_transport *transport);
 };
 
+/** Current version for the `git_transport` structure */
 #define GIT_TRANSPORT_VERSION 1
+
+/** Static constructor for `git_transport` */
 #define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION}
 
 /**
@@ -281,6 +308,7 @@ GIT_EXTERN(int) git_transport_smart_credentials(git_credential **out, git_transp
  *
  * @param out options struct to fill
  * @param transport the transport to extract the data from.
+ * @return 0 on success, or an error code
  */
 GIT_EXTERN(int) git_transport_remote_connect_options(
 		git_remote_connect_options *out,
@@ -368,7 +396,14 @@ struct git_smart_subtransport {
 	void GIT_CALLBACK(free)(git_smart_subtransport *transport);
 };
 
-/** A function which creates a new subtransport for the smart transport */
+/**
+ * A function that creates a new subtransport for the smart transport
+ *
+ * @param out the smart subtransport
+ * @param owner the transport owner
+ * @param param the input parameter
+ * @return 0 on success, or an error code
+ */
 typedef int GIT_CALLBACK(git_smart_subtransport_cb)(
 	git_smart_subtransport **out,
 	git_transport *owner,
@@ -411,6 +446,7 @@ typedef struct git_smart_subtransport_definition {
  *
  * @param out The newly created subtransport
  * @param owner The smart transport to own this subtransport
+ * @param param custom parameters for the subtransport
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_smart_subtransport_http(
@@ -423,6 +459,7 @@ GIT_EXTERN(int) git_smart_subtransport_http(
  *
  * @param out The newly created subtransport
  * @param owner The smart transport to own this subtransport
+ * @param param custom parameters for the subtransport
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_smart_subtransport_git(
@@ -435,6 +472,7 @@ GIT_EXTERN(int) git_smart_subtransport_git(
  *
  * @param out The newly created subtransport
  * @param owner The smart transport to own this subtransport
+ * @param param custom parameters for the subtransport
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_smart_subtransport_ssh(
@@ -444,4 +482,5 @@ GIT_EXTERN(int) git_smart_subtransport_ssh(
 
 /** @} */
 GIT_END_DECL
+
 #endif

data/vendor/libgit2/include/git2/tag.h

@@ -15,7 +15,7 @@
 
 /**
  * @file git2/tag.h
- * @brief Git tag parsing routines
+ * @brief A (nearly) immutable pointer to a commit; useful for versioning
  * @defgroup git_tag Git tag management
  * @ingroup Git
  * @{
@@ -335,6 +335,7 @@ typedef int GIT_CALLBACK(git_tag_foreach_cb)(const char *name, git_oid *oid, voi
  * @param repo Repository
  * @param callback Callback function
  * @param payload Pointer to callback data (optional)
+ * @return 0 on success or an error code
  */
 GIT_EXTERN(int) git_tag_foreach(
 	git_repository *repo,
@@ -380,4 +381,5 @@ GIT_EXTERN(int) git_tag_name_is_valid(int *valid, const char *name);
 
 /** @} */
 GIT_END_DECL
+
 #endif

data/vendor/libgit2/include/git2/trace.h

@@ -12,8 +12,8 @@
 
 /**
  * @file git2/trace.h
- * @brief Git tracing configuration routines
- * @defgroup git_trace Git tracing configuration routines
+ * @brief Tracing functionality to introspect libgit2 in your application
+ * @defgroup git_trace Tracing functionality to introspect libgit2 in your application
  * @ingroup Git
  * @{
  */
@@ -48,8 +48,13 @@ typedef enum {
 
 /**
  * An instance for a tracing function
+ *
+ * @param level the trace level
+ * @param msg the trace message
  */
-typedef void GIT_CALLBACK(git_trace_cb)(git_trace_level_t level, const char *msg);
+typedef void GIT_CALLBACK(git_trace_cb)(
+	git_trace_level_t level,
+	const char *msg);
 
 /**
  * Sets the system tracing configuration to the specified level with the
@@ -64,4 +69,5 @@ GIT_EXTERN(int) git_trace_set(git_trace_level_t level, git_trace_cb cb);
 
 /** @} */
 GIT_END_DECL
+
 #endif

data/vendor/libgit2/include/git2/transaction.h

@@ -12,8 +12,8 @@
 
 /**
  * @file git2/transaction.h
- * @brief Git transactional reference routines
- * @defgroup git_transaction Git transactional reference routines
+ * @brief Transactional reference handling
+ * @defgroup git_transaction Transactional reference handling
  * @ingroup Git
  * @{
  */
@@ -118,4 +118,5 @@ GIT_EXTERN(void) git_transaction_free(git_transaction *tx);
 
 /** @} */
 GIT_END_DECL
+
 #endif

data/vendor/libgit2/include/git2/transport.h

@@ -15,8 +15,8 @@
 
 /**
  * @file git2/transport.h
- * @brief Git transport interfaces and functions
- * @defgroup git_transport interfaces and functions
+ * @brief Transports are the low-level mechanism to connect to a remote server
+ * @defgroup git_transport Transports are the low-level mechanism to connect to a remote server
  * @ingroup Git
  * @{
  */
@@ -30,10 +30,18 @@ GIT_BEGIN_DECL
  * @param str The message from the transport
  * @param len The length of the message
  * @param payload Payload provided by the caller
+ * @return 0 on success or an error code
  */
 typedef int GIT_CALLBACK(git_transport_message_cb)(const char *str, int len, void *payload);
 
-/** Signature of a function which creates a transport */
+/**
+ * Signature of a function which creates a transport.
+ *
+ * @param out the transport generate
+ * @param owner the owner for the transport
+ * @param param the param to the transport creation
+ * @return 0 on success or an error code
+ */
 typedef int GIT_CALLBACK(git_transport_cb)(git_transport **out, git_remote *owner, void *param);
 
 /** @} */

data/vendor/libgit2/include/git2/tree.h

@@ -14,8 +14,8 @@
 
 /**
  * @file git2/tree.h
- * @brief Git tree parsing, loading routines
- * @defgroup git_tree Git tree parsing, loading routines
+ * @brief Trees are collections of files and folders to make up the repository hierarchy
+ * @defgroup git_tree Trees are collections of files and folders to make up the repository hierarchy
  * @ingroup Git
  * @{
  */
@@ -24,7 +24,7 @@ GIT_BEGIN_DECL
 /**
  * Lookup a tree object from the repository.
  *
- * @param out Pointer to the looked up tree
+ * @param[out] out Pointer to the looked up tree
  * @param repo The repo to use when locating the tree.
  * @param id Identity of the tree to locate.
  * @return 0 or an error code
@@ -345,6 +345,10 @@ GIT_EXTERN(int) git_treebuilder_remove(
  * The return value is treated as a boolean, with zero indicating that the
  * entry should be left alone and any non-zero value meaning that the
  * entry should be removed from the treebuilder list (i.e. filtered out).
+ *
+ * @param entry the tree entry for the callback to examine
+ * @param payload the payload from the caller
+ * @return 0 to do nothing, non-zero to remove the entry
  */
 typedef int GIT_CALLBACK(git_treebuilder_filter_cb)(
 	const git_tree_entry *entry, void *payload);
@@ -379,7 +383,14 @@ GIT_EXTERN(int) git_treebuilder_filter(
 GIT_EXTERN(int) git_treebuilder_write(
 	git_oid *id, git_treebuilder *bld);
 
-/** Callback for the tree traversal method */
+/**
+ * Callback for the tree traversal method.
+ *
+ * @param root the current (relative) root to the entry
+ * @param entry the tree entry
+ * @param payload the caller-provided callback payload
+ * @return a positive value to skip the entry, a negative value to stop the walk
+ */
 typedef int GIT_CALLBACK(git_treewalk_cb)(
 	const char *root, const git_tree_entry *entry, void *payload);
 
@@ -470,6 +481,6 @@ typedef struct {
 GIT_EXTERN(int) git_tree_create_updated(git_oid *out, git_repository *repo, git_tree *baseline, size_t nupdates, const git_tree_update *updates);
 
 /** @} */
-
 GIT_END_DECL
+
 #endif