Re: On shipping more of our technical docs as manpages

From: Jeff King <peff@peff.net>
Date: Sep 27, 2018, 18:25 UTC
Message-ID: <20180927182528.GB2468@sigill.intra.peff.net>
In-Reply-To: <xmqqwor6hmgk.fsf@gitster-ct.c.googlers.com>

On Thu, Sep 27, 2018 at 10:36:11AM -0700, Junio C Hamano wrote:

Show 12 quoted lines

> Jeff King <peff@peff.net> 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).

Show 5 quoted lines

> 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