On Tue, Dec 09, 2014 at 12:17:13PM -0800, 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? > > -- >8 -- > Subject: put strbuf API documentation in one place > > v1.8.1-rc0~61^2 (strbuf_split*(): document functions, 2012-11-04) > added some nice API documentation for a few functions to strbuf.h, to > complement the documentation at Documentation/technical/api-strbuf. > That was helpful because it meant one less hop for someone reading the > header to find API documentation. > > In practice, unfortunately, it is too hard to remember that there > is documentation in two places. The longer documentation comments > in the header made Documentation/technical/api-strbuf less > discoverable. So move the information to > Documentation/technical/api-strbuf and drop the long comments. > > Hopefully in the long term we will find a good way to > generate well organized Documentation/technical/api-* documents > from comments in headers and this problem will be eliminated > completely. > > Short reminders in the header file are still okay. I somewhat feel this goes in the opposite direction of where we want to be (all data in one place, but that place is the header). Your patch might make api-strbuf more discoverable, but it also vastly increases the chances of function getting out of sync with their documentation, or new functions being added without getting documented (very often the presence of other documentation in the comments is enough to guilt me into writing it for new ones). Elsewhere I mentioned a tool to extract comments and format them. But do people actually care about the formatting step? Does anybody asciidoc the technical/api-* files? We did not even support building them until sometime in 2012. Personally, I only ever view them as text. In which case can we simply start migrating api-strbuf.txt into in-header comments, without worrying about a parsing tool? -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