On Tue, Dec 09, 2014 at 03:18:28PM -0800, Junio C Hamano wrote: > Jonathan Nieder <jrnieder@xxxxxxxxx> writes: > > > Jeff King wrote: > > > >> Elsewhere I mentioned a tool to extract comments and format them. But do > >> people actually care about the formatting step? > > > > If formatting means "convert to a straightforward text document that I > > can read through", then I do. > > If the result becomes unparsable by AsciiDoc(or), those who > AsciiDoc'ified the api-*.txt may feel unhappy. I however strongly > suspect that the primary consumer of these api-*.txt documents are > consuming the text version, not AsciiDoc-to-html output. Yeah, that was my point. They were not even asciidoc'd for a long time, then one contributor, who does not otherwise work on the code, volunteered to asciidoc them. AFAIK there are no regular developers who wanted this feature (but I do not know for sure, which is why I asked). I do not _mind_ if they can be asciidoc'd, but if nobody does so, they are bound to develop formatting errors. And matching asciidoc syntax does come at a readability cost to the text. > The documentation that was written with an explicit purpose to serve > as documentation would explain how each pieces fit in the whole > system much better than a list of pieces extracted from per-function > comments, unless the header comment that serves as the source of > generated document is written carefully. If we split the header files sanely (i.e., to match what would be one api-* file), then I had imagined each header file having a long free-form comment at the top giving the overview, followed by commented structures and functions, with possibly other free-form comments in the middle as necessary. That's what I did for the strbuf.h conversion I just sent. > I am a bit hesitant to see us spending extra cycles either to > reinvent doxygen (if we do our own) or working around quirks in > third-party tools (if we decide to use existing ones). Me too. That's what I hoped that we could come up with a form whose in-header source is readable enough that people would use it. Then there is really no tool necessary. -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