Re: [PATCH] document string_list_clear

From: Jeff King <peff@peff.net>
Date: Dec 12, 2014, 19:24 UTC
Message-ID: <20141212192417.GA21132@peff.net>
In-Reply-To: <20141212183114.GA29365@google.com>

On Fri, Dec 12, 2014 at 10:31:14AM -0800, Jonathan Nieder wrote:

Show 7 quoted lines

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

Fair enough.

Show 10 quoted lines

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

Yeah, I had to strip the indent from:

  strbuf_init::
	description of strbuf_init...

when "strbuf_init::" went away, but it looks like I missed two of them. And I see one "/* First line" where the "header" from "Adding data to the buffer" got merged with a note. I agree those should be fixed.

I used our normal single-line comment style for most of those:

  /* Related to the size of the buffer */

in some places. But I'd be happy, too, with:

  /*
   * Related to the size of the buffer
   */

(and probably using a full sentence, or caps or underlining or something to indicate that the comment begins a new section of the header file).

Show 6 quoted lines

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

I think partially it was crossing mails. While I was writing the response that you responded to just now, I ended up postponing it for other work, and in the meantime you sent several more messages indicating you were OK with moving documentation into the headers. I almost scrapped my response, but frankly I was left a bit confused by your position, since it seemed the opposite of the 2 patches you had sent moving things out of headers.

Do not feel obligated to make me unconfused. If you are on board with putting documentation in the headers, then I think we can move forward with that plan.

So what next?

I agree there are some formatting problems in the strbuf.h patch I sent earlier. I'm happy to fix them and resend, but I'm not 100% sure that fixing all the problems I see will not leave problems for you. I can fix them and you can review if you want. Or alternatively, if you have more drastic formatting or wording changes in mind, maybe it would make sense for you to take a pass?

I _don't_ want to commit to moving all of api-* into headers myself. It's something I would rather have happen over time as people touch areas[1], because it's tedious and time-consuming. That does create an inconsistency, in the sense that some APIs will be documented in Documentation/technical, and others in their header files. But as long as each _individual_ API is documented in one or the other, I don't see that as a big problem (of course the status quo is a mix for some APIs, so we will live with that until they are touched, but that is no worse than today's state).

-Peff

[1] I had a vague plan to put new documentation into headers, and slowly
    migrate that way until we had a critical mass. But that was moving
    somewhat slowly, and obviously escaped the notice of many people. :)