On Thu, Sep 27, 2018 at 10:36:11AM -0700, Junio C Hamano wrote: > Jeff King <peff@xxxxxxxx> writes: > > > If you're interested in pulling documentation out of the header files > > and generating asciidoc from it, I'm happy to at least try keeping it up > > to date. When we started putting this information into header files, we > > used "/**" to start the comment, as a special marker to indicate it was > > worth pulling out. I don't know how well we've maintained that > > convention, but it's a starting point. > > I noticed some people add these extra asterisk at the beginning of > comment, but I do not recall that we declared it is a convention we > adopt, so I'd rather be surprised if we've "maintained" it. True. _I_ declared it as a convention and used it when I migrated some of the initial api-* documents, but I don't know if anybody else followed that lead. FWIW, it is not my own convention, but one used by other tools like doxygen (which in turn got it from javadoc, I think). > Please have it in CodingGuidelines or somewhere once this thread > settles and we decide to keep that convention (I have no problem > with the convention; it is just I personally didn't think it was > worth doing myself at least until now that we might have found > somebody who wants to make use of the markings). Yeah, this is basically why I hadn't pushed harder for it. If nobody is actually extracting based on the convention, there is not much point. So I was waiting for somebody to show up with an interest in using an extraction tool. -Peff
