Re: [PATCH] document string_list_clear

[Junio C Hamano <gitster@pobox.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

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

Yeah, I agree with the above preferred ordering, and also think once
we get to (2) it would be "usable" by the intended audience.  Those
who prefer (1) over (2) are the ones who somehow want to read hard
copies ;-) and are likely to be different audiences and are better
served by people with different skill-set and inclination.

I am not sure if (2) and (3) are that incompatible, though.  If you
had an acceptable version of (3), wouldn't it be just the matter of
indenting the whole thing with "s/^/ */", sprinkle "/**" and "*/" at
strategic paragraph breaks, and move them back to the corresponding
header?