Comment style docstrings

[Keisuke Nishida]

So far docstrings of primitive procedures have been written as
C strings in C files.  Shouldn't we use a comment style like this?

/**
 * Name: acons
 * Type: procedure
 * Args: key value alist
 * 
 * Adds a new key-value pair to @var{alist}.  A new pair is
 * created whose car is @var{key} and whose cdr is @var{value}, and the
 * pair is consed onto @var{alist}, and the new list is returned.  This
 * function is @emph{not} destructive; @var{alist} is not modified.
 */
SCM_DEFINE_PROCEDURE (scm_acons, "acons", 3, 0, 0,
                      (SCM key, SCM value, SCM alist))
#define FUNC_NAME s_scm_acons
{
  ...
}

Rationale:

 1. Docstrings are unlikely used as real C strings.
    There is no reason to represent them by C strings.

 2. Scheme files are going to use a comment style.
    We should use the same style in C files.

 3. The above style is easier to modify, read, and parse
    than the current style.

 4. Docstrings in this style can be used for non-procedures,
    including macros, classes, and smob types, without any
    extension to C code.

The only drawback I can think of is that this style of
docstrings are always extracted unconditionally regardless
of #if statements in C files (unless we parse them as well).
I think this is not a big issue.

If it is okay, I'll write a converter from the current style
to the above style, a parser for comment style docstrings, and
Emacs commands that help writing the new style of docstrings
when I have time.

Thanks,
Keisuke