Re: [PATCH] document string_list_clear

[Jonathan Nieder <jrnieder@gmail.com>]

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.

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.

It's moot given that we don't seem to disagree about what should be
done about it.  Why keep arguing?

> I think the end result that I posted is still strictly better than what
> we have currently, with the exception that I should have reformatted the
> hanging indents. What is it that you don't like about it?

Other issues of inconsistent markup.  For example, some comments are
strangely indented, and some look like

	/* First line
	 * second line
	 * third line */

> I'm not super interested in going back and forth over minor markup
> issues if there are overall issues with the concept that might block it
> from happening (just because they are tedious and time-consuming, and I
> do not want to spend a lot of time formatting something that will get
> thrown away). So please list your complaints in order of increasing
> specificity. :)

The overall concept is good.

I chose not to list markup issues for the same reason (it's more
tedious to go back and forth than for someone to spend some time to
get it mostly-right first on their own).  I am kind of confused about
the current status, since I've said again and again that I'd be happy
to see the documentation in the header but you still seem to be trying
to convince me of that.  What am I missing?

Jonathan