Re: [PATCH] document string_list_clear

Jonathan Nieder [off-list ref] 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?

Junio C Hamano wrote:

Jonathan Nieder [off-list ref] writes:

quoted

 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.

[...]

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?

Presumably.  There's also the question of whether to use asciidoc
markup, which got mixed in somehow (but I don't see why it has to be ---
a header with asciidoc would be fine with me, as would a file in
Documentation/technical/ without asciidoc).