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. -Peff -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html