Re: [PATCH v4 03/20] mktag doc: update to explain why to use this

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 23, 2020, 01:57 UTC
Message-ID: <xmqqy2hpe128.fsf@gitster.c.googlers.com>
In-Reply-To: <20201223013606.7972-4-avarab@gmail.com>

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

Show 9 quoted lines

> Change the mktag documentation to compare itself to the similar
> "hash-object -t tag" command. Before this someone reading the
> documentation wouldn't have much of an idea what the difference
> was.
>
> Let's allude to our own validation logic, and cross-link the "mktag"
> and "hash-object" documentation to aid discover-ability. A follow-up
> change to migrate "mktag" to use "fsck" validation will make the part
> about validation logic clearer.

We do not add links to refer to commands like "git commit-tree", "git mktree" or "git add" just because these other commands can create commit, tree and blob objects like hash-object does, so adding a link to mktag in the hash-object documentation feels a bit fishy, but the extended description in mktag that highlights the added value of the command over hash-object reads very well.

Show 9 quoted lines

>  Tag Format
>  ----------
> @@ -34,6 +43,10 @@ exists, is separated by a blank line from the header.  The
>  message part may contain a signature that Git itself doesn't
>  care about, but that can be verified with gpg.
>  
> +SEE ALSO
> +--------
> +linkgit:git-hash-object[1],

Comma,

> +
>  GIT
>  ---
>  Part of the linkgit:git[1] suite