On Tue, Dec 09, 2014 at 02:49:50PM -0800, Jonathan Nieder wrote: > Jonathan Nieder wrote: > > Stefan Beller wrote: > >> On Tue, Dec 9, 2014 at 11:37 AM, Junio C Hamano <gitster@xxxxxxxxx> wrote: > > >>> Perhaps the API doc that currently says "Free" is the only thing > >>> that needs fixing? And perhaps add "See $doc" at the beginning of > >>> the header and remove duplicated comments we already have in the > >>> file? > >> > >> The reason I wrote this patch originally was because I seem to forget we have > >> more than one place to document our APIs. If there are comments in the header > >> I seem to have thought it were the only place where we have documentation. > > > > How about this patch? > > And another: this goes on top or replaces the previous one? (This applies cleanly on origin/master) > -- >8-- > Subject: put string-list API documentation in one place > > Until recently (v1.8.0-rc0~46^2~5, 2012-09-12), the string-list API > was documented in detail in Documentation/technical/api-string-list.txt > and the header file contained section markers and some short reminders > but little other documentation. > > Since then, the header has acquired some more comments that are mostly > identical to the documentation from technical/. In principle that > should help convenience, since it means one less hop for someone > reading the header to find API documentation. In practice, > unfortunately, it is hard to remember that there is documentation in > two places, and the comprehensive documentation of some functions in > the header makes it too easy to forget that the other functions are > documented at all (and where). > > Add a comment pointing to Documentation/technical/ and remove the > comments that duplicate what is written there. Longer term, we may > want to move all of the technical docs to header files and generate > printer-ready API documentation another way, but that is a larger > change for another day. > > Short reminders in the header file are still okay. > > Reported-by: Stefan Beller <sbeller@xxxxxxxxxx> > Signed-off-by: Jonathan Nieder <jrnieder@xxxxxxxxx> > --- Thanks a lot for this patch. It's improving the situation a lot. No information is lost albeit many deleted lines, have a Reviewed-by: Stefan Beller <sbeller@xxxxxxxxxx> -- 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