Commit a78567c6d69c75338f7883da063f8206011b9bf6

Stefan Sperling 2020-03-18T16:11:28

document fetch API functions

diff --git a/include/got_fetch.h b/include/got_fetch.h
index f33ee90..36345e8 100644
--- a/include/got_fetch.h
+++ b/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 *);