Re: [PATCH] document string_list_clear

Jonathan Nieder [off-list ref] writes:

Jeff King wrote:

quoted

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.

quoted

                                                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.

On Tue, Dec 09, 2014 at 03:18:28PM -0800, Junio C Hamano wrote:

Jonathan Nieder [off-list ref] writes:

quoted

Jeff King wrote:

quoted

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.

Yeah, that was my point. They were not even asciidoc'd for a long time,
then one contributor, who does not otherwise work on the code,
volunteered to asciidoc them. AFAIK there are no regular developers who
wanted this feature (but I do not know for sure, which is why I asked).

I do not _mind_ if they can be asciidoc'd, but if nobody does so, they
are bound to develop formatting errors. And matching asciidoc syntax
does come at a readability cost to the text.

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.

If we split the header files sanely (i.e., to match what would be one
api-* file), then I had imagined each header file having a long
free-form comment at the top giving the overview, followed by commented
structures and functions, with possibly other free-form comments in the
middle as necessary. That's what I did for the strbuf.h conversion I
just sent.

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

Me too. That's what I hoped that we could come up with a form whose
in-header source is readable enough that people would use it. Then there
is really no tool necessary.

-Peff