Merge pull request #4954 from tiennou/fix/documentation Documentation fixes
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 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442
diff --git a/docs/error-handling.md b/docs/error-handling.md
index 8df9a40..05725f2 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 0386916..04c7300 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 7a2a023..b14f3ea 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 92cb32b..bba8fea 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 6c57ed0..0eaa004 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