Subject: Re: Is "make check-docs" useful anymore?

From: Junio C Hamano <[email-masked]>
Date: Fri, 24 Sep 2021 10:59:07 -0700

Ævar Arnfjörð Bjarmason <[email-masked]> writes:

> I didn't notice until after it hit master that this caused a regression
> in "make check-docs":
>
>     $ make -s check-docs
>     removed but documented: git-version
>
> The "fix" is rather easy, i.e. adding "git-version" to the whitelist.
>
> But I wondered about $subject, i.e. we want to run the "lint" part, but
> do we really need something reminding us that there isn't a mapping
> between Documentation/*.txt and *.o files present at the top-level?

There were multiple things check-docs wanted to catch originally.

 - commands not referred to from the main page
 - a new command added without documentation
 - an old command removed while leaving documentation

It may be that we no longer remove commands, so the last check may
be less useful.

> If we're going to keep it in pretty much its current form then the CI
> integration added in b98712b9aa9 (travis-ci: build documentation,
> 2016-05-04) seems rather useless when it comes to this, i.e. we should
> either adjust it to exit non-zero,...

Yes, that is a good thing to do.

Thanks.