diff options
author | Edward Thomson <ethomson@edwardthomson.com> | 2019-01-30 19:59:43 +0000 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-01-30 19:59:43 +0000 |
commit | 2f1d6eff31dff349d5ac3fdb15505c3d95ef4d6a (patch) | |
tree | c845d499b1d5a8cc90d8bc3c95cfa7888c8bab19 | |
parent | cf14215deda8fa8ec0da7567e15f0acb8035d162 (diff) | |
parent | 690e55e00211e7427052518d658200a5f9956240 (diff) | |
download | libgit2-2f1d6eff31dff349d5ac3fdb15505c3d95ef4d6a.tar.gz |
Merge pull request #4954 from tiennou/fix/documentation
Documentation fixes
-rw-r--r-- | docs/error-handling.md | 11 | ||||
-rw-r--r-- | include/git2/repository.h | 69 | ||||
-rw-r--r-- | include/git2/signature.h | 4 | ||||
-rw-r--r-- | include/git2/sys/transport.h | 145 | ||||
-rw-r--r-- | include/git2/types.h | 2 |
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 |