Re: [PATCH] document string_list_clear

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Dec 12, 2014, 18:31 UTC
Message-ID: <20141212183114.GA29365@google.com>
In-Reply-To: <20141212091625.GA9049@peff.net>

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 */

Show 6 quoted lines

> 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