Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@xxxxxxxxx> writes:
>> Michael Haggerty wrote:
>>> I would find it a pity for that work to be
>>> squashed into Documentation/technical/api-*.txt, where in my opinion it
>>> is less discoverable and more likely to fall into disrepair.
>>
>> I think we're in violent agreement and keep repeating ourselves.
>
> Hmph, I am confused.
>
> I somehow had an impression that the "move to doc and remove from
> header" patch was to illustrate how unpleasant the result will be as
> a whole (i.e. results in a nice documentation as a starting point,
> but we can see that it will be hard to motivate and help people to
> keep it up to date during further development). Which would suggest
> that you are in favor of moving the other way around, to keep the
> header rich with documentation only at the higher level. Am I
> reading you correctly?
Sorry, I think I was unclear.
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.
2. Move documentation to header, being careful enough that the header
sort of works as a standalone document.
3. Move documentation to Documentation/technical/ and keep the header
bare-bones.
4. Status quo (comprehensive documentation for some functions in both
places, for others in only one place, no reliable way for someone
to find the information they need in one place).
Since (3) is better than (4), I wrote simple patches to do that for
strbuf.h and string-list.h. I meant them in earnest --- I hope they
get applied.
I think peff was working on (2), which is an admirable goal. The
patch seemed to be incomplete.
Thanks,
Jonathan
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html