Re: [PATCH] document string_list_clear

[Jonathan Nieder <jrnieder@gmail.com>]

Jeff King wrote:
>> Jeff King wrote:

> We could probably do a better job of keeping our header files neat and
> well-ordered. And perhaps would so if they had a coherent narrative in
> the first place.

The example I was looking at before was refs.h.  It is still a mess.
Hopefully strbuf.h will work better.

[...]
> On Tue, Dec 09, 2014 at 02:23:37PM -0800, Jonathan Nieder wrote:

>> I suspect a simple tool to extract the comments and produce something
>> like the technical/api-* files would help, since then when someone
>> writes a patch, they could try the tool and see if the result is still
>> easy to read.
>
> That seems like wishful thinking to me. Some subset of developers will
> be happy reading the documentation in the header file, and will not
> commonly run the tool. Therefore they will also not bother to examine
> the output of the tool when making a change (either because they forget,
> or because it is simply a hassle that they do not care about).

That is okay as long as enough people extract documentation to ensure
the result is sane.

It is similar to what happens with Documentation/*.txt.  A subset of
developers just work with the source and make local changes without
looking at the big picture (and sometimes buggy markup or documentation
organized in a confusing way results).  But that doesn't change much.
When people forget to look at the manpage and write text that is
awkward in context or markup errors, one of a few things happens:

 * a reviewer notices.  The patch is fixed, and the patch author
   develops better habits for next time.

 * someone using the documentation notices later, and it gets fixed
   then, which is still fine.

Both outcomes are much, much better than documentation that never gets
organized.

[...]
>                               The api-* files have slowly grown out of
> date over the years, and I believe that is because they are too far
> removed from the code people are actually touching.

I don't think they ever were very comprehensive or up to date.

As far as I understand, the api-* files are intended to be usually out
of date.  Their main purpose is to explain the gist of how to use the
API.  They were usually written way after the API was introduced (so
they are behind already).  They are clearly written and as long as
they mostly match the code, that is enough for them to be useful and
educational.

Then every few years or so, someone updates the file with the latest
API changes, still with an eye to overall organization and readability
of the document.

In other words, they prioritize clarity over currency.

Of course if it's possible to have clear documentation that also
matches the current code, that would be even better.  I have hope that
moving the documentation to the header files will get us there if we
do it right.

> I did drop some asciidoc-specific formatting from the main text (e.g.,
> "+" lines for connecting blocks), which means that extracting the result
> and running it through asciidoc won't work.

This unfortunately lost some structure (e.g., which paragraphs were
part of the same bulleted list).  It would be more common to use a
hanging indent:

 - The `buf` member is never NULL, so ...
   string operations ...
   by `strbuf_init()` ...

   Do not assume anything about what `buf` really is ...
   ...

 - ...

[...]
>                                             I think it makes the actual
> text much more readable, though. But we could do it the other way if
> people really want to asciidoc it.

I also don't mind losing the asciidoc markup, especially given that it
would be a pain to reconstruct and render.

My reaction at first glance is that this is trying to do something
good but the current implementation is less readable than
Documentation/technical/api-strbuf.txt.  Am I looking at a work in
progress, or is this meant to be ready for application?  Which aspects
would you be interested in comments on?

Thanks,
Jonathan