Re: [PATCH] document string_list_clear

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 9, 2014, 23:18 UTC
Message-ID: <xmqq61dkl8e3.fsf@gitster.dls.corp.google.com>
In-Reply-To: <20141209222337.GA16345@google.com>

Jonathan Nieder <jrnieder@gmail.com> writes:

Show 7 quoted lines

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

Show 12 quoted lines

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