Re: [PATCH] document string_list_clear

[Jeff King <peff@peff.net>]

On Tue, Dec 09, 2014 at 11:41:44AM -0800, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > Also, I forgot to mention: if we consistently put the API docs into the
> > header files and extracted it automatically into standalone documents,
> > we would not need to have two places.
> >
> > This is something I've been meaning to look at for a long time, but it
> > never quite makes the priority list. And my past experiences with tools
> > like doxygen has been that they are complicated and have a lot of
> > dependencies. It's been a long time since I've tried, though.
> 
> Yeah, that is a thought.
> 
> Some existing documentation pages like allocation-growing may not be
> a good match for this strategy, though; cache.h has a lot more than
> just alloc-grow, and there needs to be a way to generate more than
> one API docs from a single header (and vice versa, taking text from
> more than one source for a single API, I suspect).

I think that would be a matter of tool support for saying "now I am
outputting api-foo" in the inline documentation[1]. It does make writing
Makefiles a lot harder, though, if there isn't a one-to-one
correspondence between targets and their sources. Perhaps it is a sign
that we should split our include files more along functional boundaries.
If we cannot make sane documentation out of the file, then it is
probably confusing for humans to read it.

Opening cache.h shows it starting with git_{in,de}flate_*, and then
DEFAULT_GIT_PORT!? It has long been a dumping ground for random global
functions and definitions. If we are going to document subsystems,
splitting them into their own files seems sensible. Skimming through the
file, some of the splits seem pretty easy and obvious.

-Peff

[1] I do not have a tool in mind, so this is something to think about
    while evaluating them. It seems like just parsing:

    /**
     * All of this will get dumped in a file (sans asterisks),
     * which can then be fed to asciidoc. The "**" marker
     * starts the docstring, which ends at the normal comment
     * boundary.
     */

    would be an easy place to start, and by implementing it ourselves
    with sed we would be free to implement any other rules we wanted.
    That is probably too naive, though. It would be nice if the tool
    actually understood C function declarations, so that we would not
    have to repeat them manually in the comments.

    I guess all tools like doxygen probably started off as "just pull
    out and format the comments", and then grew and grew in complexity. :)