Commit 0c60ce5ab29975b198dec154bc2ebbea83916eb9

Stefan Sperling 2018-04-02T11:10:05

document the current public API

diff --git a/include/got_diff.h b/include/got_diff.h
index f7ac2b2..4673b9c 100644
--- a/include/got_diff.h
+++ b/include/got_diff.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017 Stefan Sperling <stsp@openbsd.org>
+ * Copyright (c) 2018 Stefan Sperling <stsp@openbsd.org>
  *
  * Permission to use, copy, modify, and distribute this software for any
  * purpose with or without fee is hereby granted, provided that the above
@@ -14,7 +14,18 @@
  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  */
 
+/*
+ * Compute the differences between two blobs and write unified diff text
+ * to the provided output FILE. Two const char * diff header labels may
+ * be provided which will be used to identify each blob in the diff output.
+ * If a label is NULL, use the blob's SHA1 checksum instead.
+ */
 const struct got_error *got_diff_blob(struct got_blob_object *,
     struct got_blob_object *, const char *, const char *, FILE *);
+
+/*
+ * Compute the differences between two trees and write unified diff text
+ * to the provided output FILE.
+ */
 const struct got_error *got_diff_tree(struct got_tree_object *,
     struct got_tree_object *, struct got_repository *, FILE *);
diff --git a/include/got_error.h b/include/got_error.h
index ad4669b..4927b60 100644
--- a/include/got_error.h
+++ b/include/got_error.h
@@ -80,6 +80,21 @@ static const struct got_error {
 	{ GOT_ERR_WORKTREE_BUSY,"worktree already locked" },
 };
 
-const struct got_error * got_error(int code);
+/*
+ * Get an error object from the above list, for a given error code.
+ * The error message is fixed.
+ */
+const struct got_error *got_error(int);
+
+/*
+ * Get a statically allocated error object with code GOT_ERR_ERRNO
+ * and an error message obtained from strerror(3).
+ */
 const struct got_error *got_error_from_errno(void);
+
+/*
+ * If ferror(3) indicates an error status for the FILE, obtain an error
+ * from got_error_from_errno(). Else, obtain the error via got_error()
+ * with the error code provided in the second argument.
+ */
 const struct got_error *got_ferror(FILE *, int);
diff --git a/include/got_object.h b/include/got_object.h
index 2b3af38..335f73e 100644
--- a/include/got_object.h
+++ b/include/got_object.h
@@ -44,6 +44,7 @@ struct got_commit_object {
 	char *logmsg;
 };
 
+/* A generic object. Used as a handle which holds an ID and an object type. */
 struct got_object;
 #define GOT_OBJ_TYPE_COMMIT		1
 #define GOT_OBJ_TYPE_TREE		2
@@ -55,27 +56,115 @@ struct got_object;
 
 struct got_repository;
 
+/*
+ * Obtain a string representation of an object ID. The output depends on
+ * the hash function used by the repository format (currently SHA1).
+ */
 const struct got_error *got_object_id_str(char **, struct got_object_id *);
+
+/*
+ * Compare two object IDs. Return value behaves like memcmp(3).
+ */
 int got_object_id_cmp(struct got_object_id *, struct got_object_id *);
+
+/*
+ * Created a newly allocated copy of an object ID.
+ * The caller should dispose of it with free(3).
+ */
 struct got_object_id *got_object_id_dup(struct got_object_id *);
+
+/*
+ * Get a newly allocated copy of an object's ID.
+ * The caller should dispose of it with free(3).
+ */
 struct got_object_id *got_object_get_id(struct got_object *);
+
+/*
+ * Obtain the type of an object.
+ * Returns one of the GOT_OBJ_TYPE_x values (see above).
+ */
 int got_object_get_type(struct got_object *);
+
+/*
+ * Attempt to open the object in a repository with the provided ID.
+ * Caller must dispose of it with got_object_close().
+ */
 const struct got_error *got_object_open(struct got_object **,
     struct got_repository *, struct got_object_id *);
+
+/*
+ * Attempt to map the provided ID string to an object ID and then
+ * attempt to open the object in a repository with this ID.
+ * The form of an ID string depends on the hash function used by the
+ * repository format (currently SHA1).
+ * Caller must dispose of the object with got_object_close().
+ */
 const struct got_error *got_object_open_by_id_str(struct got_object **,
-    struct got_repository *, const char *); 
+    struct got_repository *, const char *);
+
+/* Dispose of an object. */
 void got_object_close(struct got_object *);
+
+/*
+ * Attempt to open a commit object in a repository.
+ * The provided object must be of type GOT_OBJ_TYPE_COMMIT.
+ * The caller must dispose of the commit with got_object_commit_close().
+ */
 const struct got_error *got_object_commit_open(struct got_commit_object **,
     struct got_repository *, struct got_object *);
+
+/* Dispose of a commit object. */
 void got_object_commit_close(struct got_commit_object *);
+
+/*
+ * Attempt to open a tree object in a repository.
+ * The provided object must be of type GOT_OBJ_TYPE_TREE.
+ * The caller must dispose of the tree with got_object_tree_close().
+ */
 const struct got_error *got_object_tree_open(struct got_tree_object **,
     struct got_repository *, struct got_object *);
+
+/* Dispose of a tree object. */
 void got_object_tree_close(struct got_tree_object *);
+
+/*
+ * Attempt to open a blob object in a repository.
+ * The provided object must be of type GOT_OBJ_TYPE_BLOB.
+ * The size_t argument specifies the block size of an associated read buffer.
+ * The caller must dispose of the blob with got_object_blob_close().
+ */
 const struct got_error *got_object_blob_open(struct got_blob_object **,
     struct got_repository *, struct got_object *, size_t);
+
+/* Dispose of a blob object. */
 void got_object_blob_close(struct got_blob_object *);
+
+/*
+ * Write the string representation of the object ID of a blob to a buffer.
+ * The size_t argument speficies the size of the buffer. In the current
+ * implementation, it must be at least SHA1_DIGEST_STRING_LENGTH bytes.
+ * XXX This is a bad API, use got_object_id_str() instead.
+ */
 char *got_object_blob_id_str(struct got_blob_object*, char *, size_t);
+
+/*
+ * Get the length of header data at the beginning of the blob's read buffer.
+ * Note that header data is only present upon the first invocation of
+ * got_object_blob_read_block() after the blob is opened.
+ */
 size_t got_object_blob_get_hdrlen(struct got_blob_object *);
+
+/*
+ * Get a pointer to the blob's read buffer.
+ * The read buffer is filled by got_object_blob_read_block().
+ */
 const uint8_t *got_object_blob_get_read_buf(struct got_blob_object *);
+
+/*
+ * Read the next chunk of data from a blob, up to the blob's read buffer
+ * block size. The size_t output argument indicates how many bytes have
+ * been read into the blob's read buffer. Zero bytes will be reported if
+ * all data in the blob has been read.
+ */
 const struct got_error *got_object_blob_read_block(size_t *,
     struct got_blob_object *);
diff --git a/include/got_reference.h b/include/got_reference.h
index 9c30c84..d8b1b74 100644
--- a/include/got_reference.h
+++ b/include/got_reference.h
@@ -26,10 +26,25 @@ struct got_reference;
 struct got_repository;
 struct got_object_id;
 
+/*
+ * Attempt to open the reference with the provided name in a repository.
+ * The caller must dispose of it with got_ref_close().
+ */
 const struct got_error * got_ref_open(struct got_reference **,
     struct got_repository *, const char *);
+
+/* Dispose of a reference. */
 void got_ref_close(struct got_reference *);
+
+/*
+ * Create a duplicate copy of a reference.
+ * The caller must dispose of this copy with got_ref_close().
+ */
 struct got_reference *got_ref_dup(struct got_reference *);
+
+/* Attempt to resolve a reference to an object ID. */
 const struct got_error *got_ref_resolve(struct got_object_id **,
     struct got_repository *, struct got_reference *);
+
+/* Return a string representation of a reference. */
 char *got_ref_to_str(struct got_reference *);
diff --git a/include/got_repository.h b/include/got_repository.h
index 96f1b71..c60c51c 100644
--- a/include/got_repository.h
+++ b/include/got_repository.h
@@ -16,10 +16,14 @@
 
 struct got_repository;
 
-/* Open and close git repositories. */
+/* Open and close repositories. */
 const struct got_error *got_repo_open(struct got_repository**, const char *);
 void got_repo_close(struct got_repository*);
 
+/*
+ * Obtain paths to various directories within a repository.
+ * The caller must dispose of a path with free(3).
+ */
 char *got_repo_get_path(struct got_repository *);
 char *got_repo_get_path_git_dir(struct got_repository *);
 char *got_repo_get_path_objects(struct got_repository *);
@@ -28,6 +32,9 @@ char *got_repo_get_path_refs(struct got_repository *);
 
 struct got_reference;
 
-/* Get a reference, by name, from a repository. */
+/*
+ * Obtain a reference, by name, from a repository.
+ * The caller must dispose of it with got_ref_close().
+ */
 const struct got_error *got_repo_get_reference(struct got_reference **,
     struct got_repository *, const char *);
diff --git a/include/got_worktree.h b/include/got_worktree.h
index 9031acf..f4b03a4 100644
--- a/include/got_worktree.h
+++ b/include/got_worktree.h
@@ -16,13 +16,49 @@
 
 struct got_worktree;
 
+/*
+ * Attempt to initialize a new work tree on disk.
+ * The first argument is the path to a directory where the work tree
+ * will be created. The path itself must not yet exist, but the dirname(3)
+ * of the path must already exist.
+ * The reference provided will be used as the new worktree's HEAD.
+ * The third argument speficies the work tree's path prefix.
+ */
 const struct got_error *got_worktree_init(const char *, struct got_reference *,
     const char *, struct got_repository *);
+
+/*
+ * Attempt to open a worktree at the specified path.
+ * The caller must dispose of it with got_worktree_close().
+ */
 const struct got_error *got_worktree_open(struct got_worktree **, const char *);
+
+/* Dispose of an open work tree. */
 void got_worktree_close(struct got_worktree *);
+
+/*
+ * Get the path to the repository associated with a worktree.
+ * The caller must dispose of it with free(3).
+ */
 char *got_worktree_get_repo_path(struct got_worktree *);
+
+/*
+ * Get the name of a work tree's HEAD reference.
+ * The caller must dispose of it with free(3).
+ */
 char  *got_worktree_get_head_ref_name(struct got_worktree *);
+
+/* A callback function which is invoked when a path is checked out. */
 typedef void (*got_worktree_checkout_cb)(void *, const char *);
+
+/*
+ * Attempt to check out files into a work tree from its associated repository
+ * and path prefix, and update the work tree's file index accordingly.
+ * File content is obtained from blobs within the work tree's path prefix
+ * inside the tree resolved via the provided reference.
+ * The checkout progress callback will be invoked with the provided
+ * void * argument, and the path of each checked out file.
+ */
 const struct got_error *got_worktree_checkout_files(struct got_worktree *,
     struct got_reference *, struct got_repository *,
-    got_worktree_checkout_cb progress_cb, void *progress_arg);
+    got_worktree_checkout_cb progress, void *);