Re: [PATCH] document string_list_clear

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

Jonathan Nieder <jrnieder@gmail.com> writes:

> Jeff King wrote:
>
>> Elsewhere I mentioned a tool to extract comments and format them. But do
>> people actually care about the formatting step?
>
> If formatting means "convert to a straightforward text document that I
> can read through", then I do.

If the result becomes unparsable by AsciiDoc(or), those who
AsciiDoc'ified the api-*.txt may feel unhappy.  I however strongly
suspect that the primary consumer of these api-*.txt documents are
consuming the text version, not AsciiDoc-to-html output.

>>                                                 Does anybody asciidoc
>> the technical/api-* files? We did not even support building them until
>> sometime in 2012. Personally, I only ever view them as text.
>
> I also view them as text.  I tend to find it easier to read the
> technical/api-* files than headers.  That might be for the same reason
> that some other people prefer header files --- a
> Documentation/technical/ file tends to be written in one chunk
> together and ends up saying exactly what I need to know about the
> calling sequence in a coherent way, while header files tend to evolve
> over time to match the implementation without maintaining that
> organization and usability.

The documentation that was written with an explicit purpose to serve
as documentation would explain how each pieces fit in the whole
system much better than a list of pieces extracted from per-function
comments, unless the header comment that serves as the source of
generated document is written carefully.  But as people pointed out,
having the same set of information in two places in sync forces us
to be extra careful in a different way.  There is no free lunch.

We would want (1) documentation in one place, (2) easy access to it
when deciding which API function to call with what information, and
(3) make it hard to forget updating the documentation when making
changes to the API.  If that single source of truth is the header
file, perhaps we would become more careful commenting our headers
(i.e. "do not just comment each functions and structures, but
enhance introductory part that describes how things fit together"),
so I think it would be OK in the end.  We may need to reorganize and
reorder the headers so that associated comments to functions and
data types match desirable presentation order, but that effort will
kill two birds with one stone.  The resulting header would also be
easier to read by humans.

I am a bit hesitant to see us spending extra cycles either to
reinvent doxygen (if we do our own) or working around quirks in
third-party tools (if we decide to use existing ones).

Thanks.