Re: [PATCH 1/4] strbuf: migrate api-strbuf.txt documentation to strbuf.h

From: Jeff King <peff@peff.net>
Date: Dec 12, 2014, 21:40 UTC
Message-ID: <20141212214010.GA27530@peff.net>
In-Reply-To: <20141212212800.GA27451@peff.net>

On Fri, Dec 12, 2014 at 04:28:00PM -0500, Jeff King wrote:

>  1. All comments created in this way are started with "/**"
>     to indicate they are part of the API documentation. This
>     may help later with extracting the text to pretty-print
>     it.

By the way, two thoughts I had while working on this.

One, I wonder if it would look nicer to drop the leading " * " from our comments, especially for long, free-form text blocks. Like:

/**

Data Structures ---------------

This is actual asciidoc that can be rendered. It's not _nearly_ as ugly to leave the asciidoc intact if you avoid the leading asterisks.

*/

I also wondered if you could spell it as:

#ifdef API_DOCUMENTATION ... some asciidoc goes here... #endif

but the preprocessor does still look at the contents. I didn't check the standard, but I suspect an implementation doesn't _have_ to, but gcc will warn about things like unmatched single-quotes in the content.

And two, the editor support for writing comments like this is not as good. For instance, vim's "reformat paragraph" command considers the whole comment to be the paragraph. If you're writing asciidoc inside the comment field, this quickly becomes annoying. This is a minor issue that can be fixed (I am sure there is probably a vim package to do it better already, and that emacs people will tsk tsk and explain why their editor is better), but I thought I would note it as a potential "con" of this approach.

-Peff