transport: enhance documentation
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
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);
/** @} */