Re: [PATCH] document string_list_clear

From: Stefan Beller <sbeller@google.com>
Date: Dec 12, 2014, 19:19 UTC
Message-ID: <CAGZ79kbKCRKyugTnnx34AkeqN0NDBL_J2yGky06E+263oQ_6hg@mail.gmail.com>
In-Reply-To: <20141212183114.GA29365@google.com>

On Fri, Dec 12, 2014 at 10:31 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

Show 20 quoted lines

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

So you proposed an order of desirability w.r.t. the way we want to go documenting things.

> Some possibilities, in order of my preference (earlier items are better):
>
>  1. Move documentation to header and provide a program to generate a nice
>     standalone document.

Junio agrees with that order. Michael said

> My vote is for putting the API docs in the header files:

which seems to be an agreement with your most desired way to do it.

Jeff said earlier when reviewing your patch:

> I somewhat feel this goes in the opposite direction of where we want to
> be *(all data in one place, but that place is the header)*.

which sounds to me as if he prefers also the header as the one place of truth.

I do agree on your proposed order of desirability as well. So nobody showed up yet, who dislikes the headers as the one place of truth.

So the open question is:
* The historic reasoning to introduce technical/api-$header at all. As
Junio mainly
  put persons to ask into the stubs in 530e741c726 (2007-11-24, Start
preparing the API documents.),
  it was probably improving the status quo back then. Maybe it was
easier to have all names in place
  than using git blame/git pickaxe at the time?
  Answering this question makes sure we don't oversee some reasons.

* Assuming we put everything into headers now, we'd need to discuss
  -> Do we want to extract it to technical/api-$somedoc later at all?
(There seems to be some disagreement?)
  -> How do we extract (plain sed for lines starting with "*", or
doxygen, or a self cooked script)
  -> How do we ensure the generated documentation doesn't get stale over time?

As I personally just look up things in the header anyway, I'd rather get started on polishing the comments in the headers as on arguing how to extract it. Though that's a required step to know which format we want in the headers.

Thanks, Stefan