Re: [PATCH] document string_list_clear

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

Jonathan Nieder <jrnieder@gmail.com> writes:

> Jeff King wrote:
>
>> I'm not sure any such thought as "intended to be out of date" went into
>> it.
>
> Junio started the documentation in v1.5.4-rc1~49 (2007-11-24).  I'm
> not sure if there was a discussion preceding that commit.  My
> understanding was always that putting the documentation out-of-line
> was an intentional decision and that it was understood that the
> documentation would have cycles of falling out of date and needing to
> be updated, but I may be misunderstanding the history.

There of course was not "intended to be out of date".  It was just
that the prevailing style of comments in the header back then was
sporadic per-function explanation that would have served only as a
reminder for those who have read the corresponding *.c file, without
any overall structure of the API described.

We could have gone to "in header description" route back then and
the commit you referred to could have added

	/*
         * NEEDSWORK: describe the overall structure of the API
         * here, so that people can use it without reading the
         * implementation of the API itself.
         */

to each header file instead.  I chose not to primarily because those
who wanted to have documentation pages that are pointed from api-index
were audience different from those who updated *.[ch] files, and also
I had slight preference to have a set of *.txt files that do not force
me to squelch /* * * */ while reading them.

> Separate from the question of history, I honestly prefer this way of
> doing API documentation relative to 90% of the API documentation in
> headers I've seen in other projects.  I suspect you don't.  That's
> okay --- it's possible for rational people to disagree about things.

Yes.

> The overall concept is good.

OK, then let's agree to go in the "comprehensive doc in the *.h and
then those who want *.txt can help the machinery to extract"
direction.

Thanks.