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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 24, 2021, 17:59 UTC
Message-ID: <xmqqpmsxvor8.fsf@gitster.g>
In-Reply-To: <87o88i2keu.fsf@evledraar.gmail.com>

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

Show 11 quoted lines

> 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.