commit a78567c6d69c75338f7883da063f8206011b9bf6
from: Stefan Sperling <stsp@stsp.name>
date: Wed Mar 18 16:11:28 2020 UTC

document fetch API functions

commit - ceee4c0f4a8b5ade21103c1c40c3de86b328156f
commit + a78567c6d69c75338f7883da063f8206011b9bf6
blob - f33ee90db862279d91ceb7d55daac8ab8ff3aab7
blob + 36345e86940fffeffb539c6aa44c66858f3a4bd9
--- include/got_fetch.h
+++ include/got_fetch.h
@@ -18,12 +18,32 @@
 #define GOT_DEFAULT_GIT_PORT		9418
 #define GOT_DEFAULT_GIT_PORT_STR	"9418"
 
+/*
+ * Attempt to parse a URI into the following parts:
+ * A protocol scheme, hostname, port number (as a string), path on server,
+ * and a repository name. If the URI lacks some of this information return
+ * default values where applicable.
+ * The results of this function must be passed to other functions below.
+ * The caller should dispose of the returned values with free(3).
+ */
 const struct got_error *got_fetch_parse_uri(char **, char **, char **,
     char **, char **, const char *);
 
+/*
+ * Attempt to open a connection to a server using the provided protocol
+ * scheme, hostname port number (as a string) and server-side path.
+ * If successful return an open file descriptor for the connection which can
+ * be passed to other functions below, and must be disposed of with close(2).
+ */
 const struct got_error *got_fetch_connect(int *, const char *, const char *,
     const char *, const char *);
 
+/*
+ * Attempt to fetch a packfile from a server. This pack file will contain
+ * objects which that are not yet contained in the provided repository.
+ * Return the hash of the packfile (in form of an object ID) and lists of
+ * references and symbolic references learned from the server.
+ */
 const struct got_error *got_fetch_pack(struct got_object_id **,
 	struct got_pathlist_head *, struct got_pathlist_head *, int,
 	struct got_repository *);