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

[Jeff King <peff@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