Re: [PATCH 4/5] shallow.h: document '{commit,rollback}_shallow_file'

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Apr 29, 2020, 22:53 UTC
Message-ID: <CAPig+cRd4cfig5N29hkKTS8jnD+Vr96a0Tx5p0=DFZtg9KpXLw@mail.gmail.com>
In-Reply-To: <7828def924a767e54dd43b6c107e8f98c1698f55.1588199705.git.me@ttaylorr.com>

On Wed, Apr 29, 2020 at 6:39 PM Taylor Blau <me@ttaylorr.com> wrote:

> When 'commit_shallow_file()' and 'rollback_shallow_file()' were
> introduced, they did not have an documenting comment, when they could
> have benefited from one.

"an" seems wrong; did you mean "a" or "any"? Or, rewrite as: "...they were not documented...".

Show 16 quoted lines

> Add a brief note about what these functions do, and make a special note
> that they reset stat-validity checks.
>
> Signed-off-by: Taylor Blau <me@ttaylorr.com>
> ---
> diff --git a/shallow.h b/shallow.h
> @@ -10,6 +10,10 @@ void set_alternate_shallow_file(struct repository *r, const char *path, int over
>  int register_shallow(struct repository *r, const struct object_id *oid);
>  int unregister_shallow(const struct object_id *oid);
>  int is_repository_shallow(struct repository *r);
> +/*
> + * {commit,rollback}_shallow_file commits or performs a rollback to the
> + * '.git/shallow' file, respectively, and resets stat-validity checks.
> + */
>  int commit_shallow_file(struct repository *r, struct lock_file *lk);
>  void rollback_shallow_file(struct repository *r, struct lock_file *lk);

Or, simpler:

    /* commit .git/shallow and reset stat-validity checks */
    int commit_shallow_file(...);
    /* rollback .git/shallow and reset stat-validity checks */
    void rollback_shallow_file(...);