[PATCH v4 1/4] bundle API: start writing API documentation

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Sep 5, 2021, 07:34 UTC
Message-ID: <patch-v4-1.4-05be8cb0fc3-20210905T072750Z-avarab@gmail.com>
In-Reply-To: <cover-v4-0.4-00000000000-20210905T072750Z-avarab@gmail.com>

There are no other API docs in bundle.h, but this is at least a start. We'll add a parameter to this function in a subsequent commit, but let's start by documenting it.

The "/**" comment (as opposed to "/*") signifies the start of API documentation. See [1] and bdfdaa4978d (strbuf.h: integrate api-strbuf.txt documentation, 2015-01-16) and 6afbbdda333 (strbuf.h: unify documentation comments beginnings, 2015-01-16) for a discussion of that convention.

1. https://lore.kernel.org/git/874kbeecfu.fsf@evledraar.gmail.com/

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 bundle.h | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/bundle.h b/bundle.h
index 1927d8cd6a4..84a6df1b65d 100644
--- a/bundle.h
+++ b/bundle.h
@@ -27,6 +27,13 @@ int create_bundle(struct repository *r, const char *path,
 		  int version);
 int verify_bundle(struct repository *r, struct bundle_header *header, int verbose);
 #define BUNDLE_VERBOSE 1
+
+/**
+ * Unbundle after reading the header with read_bundle_header().
+ *
+ * We'll invoke "git index-pack --stdin --fix-thin" for you on the
+ * provided `bundle_fd` from read_bundle_header().
+ */
 int unbundle(struct repository *r, struct bundle_header *header,
 	     int bundle_fd, int flags);
 int list_bundle_refs(struct bundle_header *header,

-- 
2.33.0.813.g41c39388776