Re: [RFC PATCH 2/5] branch: document the usage of certain parameters

[Junio C Hamano <gitster@pobox.com>]

Kaartic Sivaraam <kaarticsivaraam91196@gmail.com> writes:

> Documentation for a certain function was incomplete as it didn't say
> what certain parameters were used for.
>
> So, document them for the sake of completeness and easy reference.

Thanks.

> @@ -15,6 +15,11 @@
>   *
>   *   - reflog creates a reflog for the branch
>   *
> + *   - if 'force' is true, clobber_head indicates whether the branch could be
> + *     the current branch; else it has no effect

Everybody else in this list begins with what it is describing for
easy eyeballing.  Can you make this match that pattern?

Also, what does "could be" mean in that sentence?  Is the caller
telling the function "how, I do not exactly know if that is the
case, but the branch I am asking to create you might be the same
branch as what is currently checked out, so be extra careful"?

Or is the comment telling a potential caller that it can pass true
to signal that create_branch() is allowed to (re)"create" the branch
that is already checked out (hence it already exists)?

I think the confusing statement above arises because an assumption
is unstated there.  If the reader knows "Even with force, calling
create_branch() on the currently checked out branch is normally
forbidden", then the reader can guess your "could" mean the latter.

	- clobber_head_ok allows the currently checked out (hence
          existing) branch to be overwritten; without force, it has
          no effect.

perhaps?  As the underlying helper calls it clobber_head_ok, and
that name is more clearly expresses that this is a permission than
the current name, I chose to add _ok to the above example, but if
you are to take the suggestion, you'd need to also update the names
in the declaration, too.

> + *
> + *   - quiet suppresses tracking information
> + *
>   *   - track causes the new branch to be configured to merge the remote branch
>   *     that start_name is a tracking branch for (if any).
>   */