Commit 2f1d6eff31dff349d5ac3fdb15505c3d95ef4d6a

Edward Thomson 2019-01-30T19:59:43

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