Re: [PATCH 4/4] Add a function string_list_longest_prefix()

> On Mon, Sep 10, 2012 at 09:24:17AM -0700, Junio C Hamano wrote:
> 
>>> While we're on the subject, it seems to me that documenting APIs like
>>> these in separate files under Documentation/technical rather than in the
>>> header files themselves
>>>
>>> - makes the documentation for a particular function harder to find,
>>>
>>> - makes it easier for the documentation to get out of sync with the
>>> actual collection of functions (e.g., the 5 undocumented functions
>>> listed above).
>>>
>>> - makes it awkward for the documentation to refer to particular function
>>> parameters by name.
>>>
>>> While it is nice to have a high-level prose description of an API, I am
>>> often frustrated by the lack of "docstrings" in the header file where a
>>> function is declared.  The high-level description of an API could be put
>>> at the top of the header file.
>>>
>>> Also, better documentation in header files could enable the automatic
>>> generation of API docs (e.g., via doxygen).
>>
>> Yeah, perhaps you may want to look into doing an automated
>> generation of Documentation/technical/api-*.txt files out of the
>> headers.
> 
> I was just documenting something in technical/api-* the other day, and
> had the same feeling. I'd be very happy if we moved to some kind of
> literate-programming system. I have no idea which ones are good or bad,
> though. I have used doxygen, but all I remember is it being painfully
> baroque. I'd much rather have something simple and lightweight, with an
> easy markup format. For example, this:
> 
>    http://tomdoc.org/
> 
> Looks much nicer to me than most doxygen I've seen. But again, it's been
> a while, so maybe doxygen is nicer than I remember.
>