Re: [PATCH] document string_list_clear

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 10, 2014, 23:04 UTC
Message-ID: <xmqq61djf6nq.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20141210223721.GG16345@google.com>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 21 quoted lines

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