| Message ID | patch-v2-1.4-dc8591f6d0b-20210823T110136Z-avarab@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | bundle: show progress on "unbundle" | expand |
On 8/23/2021 7:02 AM, Ævar Arnfjörð Bjarmason wrote: > 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. > > 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 > + > +/** nit: what's the use of the "/**" start to these doc comments? I see examples in the codebase of both, but we are not consistent even within a single file. Here is how I counted instances of each: $ git grep "^/\\*\\*\$" -- *.h | wc -l 266 $ git grep "^/\\*\$" -- *.h | wc -l 775 So we use "/*" three times as often as "/**". Should we attempt to be more consistent in the future? Thanks, -Stolee
On Tue, Aug 24 2021, Derrick Stolee wrote: > On 8/23/2021 7:02 AM, Ævar Arnfjörð Bjarmason wrote: >> 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. >> >> 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 >> + >> +/** > > nit: what's the use of the "/**" start to these doc comments? > > I see examples in the codebase of both, but we are not consistent even > within a single file. Here is how I counted instances of each: > > $ git grep "^/\\*\\*\$" -- *.h | wc -l > 266 > $ git grep "^/\\*\$" -- *.h | wc -l > 775 > > So we use "/*" three times as often as "/**". Should we attempt to > be more consistent in the future? They're not the same thing. "/*\n" is a normal comment, "/**\n" is an API documentation comment. Looking around I don't think this was documented in CodingGuidelines, but see bdfdaa4978d (strbuf.h: integrate api-strbuf.txt documentation, 2015-01-16) and 6afbbdda333 (strbuf.h: unify documentation comments beginnings, 2015-01-16). This is commonly supported by various tooling, e.g. in GNU Emacs a "/**" comment is highlighted differently than a "/*" comment (font-lock-doc-face v.s. font-lock-comment-face). So e.g. something_followed_by_open_close_parens() in a comment in C code will be highlighted as a function name with a "/**" comment, but not with a "/*" comment. I imagine that the same is true of various other editors/tooling.
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,
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. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- bundle.h | 7 +++++++ 1 file changed, 7 insertions(+)