strbuf.h: integrate api-strbuf.txt documentation

Some of strbuf is documented as comments above functions,
and some is separate in Documentation/technical/api-strbuf.txt.
This makes it annoying to find the appropriate documentation.
We'd rather have it all in one place, which means all in the
text document, or all in the header.

Let's choose the header as that place. Even though the
formatting is not quite as pretty, this keeps the
documentation close to the related code.  The hope is that
this makes it easier to find what you want (human-readable
comments are right next to the C declarations), and easier
for writers to keep the documentation up to date.

This is more or less a straight import of the text from
api-strbuf.txt into C comments, complete with asciidoc
formatting. The exceptions are:

 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.

 2. Function descriptions do not repeat the function name,
    as it is available in the context directly below.  So:

      `strbuf_add`::

          Add data of given length to the buffer.

    from api-strbuf.txt becomes:

      /**
       * Add data of given length to the buffer.
       */
      void strbuf_add(struct strbuf *sb, const void *, size_t);

    As a result, any block-continuation required in asciidoc
    for that list item was dropped in favor of straight
    blank-line paragraph (since it is not necessary when we
    are not in a list item).

 3. There is minor re-wording to integrate existing comments
    and api-strbuf text. In each case, I took whichever
    version was more descriptive, and eliminated any
    redundancies. In one case, for strbuf_addstr, the api
    documentation gave its inline definition; I eliminated
    this as redundant with the actual definition, which can
    be seen directly below the comment.

 4. The functions in the header file are re-ordered to match
    the ordering of the API documentation, under the
    assumption that more thought went into the grouping
    there.

Helped-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

0 files changed, 0 insertions, 0 deletions