13.9 guile-tools c2doc

See Doc Extraction from C Source, for discussion.

Usage: c2doc [--cpp CPP-PROG] -o OUTFILE INFILE -- [CPP-OPTIONS ...]

Process INFILE using the C pre-processor, passing CPP-OPTIONS ... to it.
Note the "--" used to mark the start of the CPP-OPTIONS.  Write output
to a file named OUTFILE, typically named with .doc extension.  If errors
occur during C pre-processor operation, OUTFILE is not written and c2doc
exits failurefully.

During snarfing, the pre-processor macro SCM_MAGIC_SNARFER is defined,
enabling recognition of SCM_REGISTER_PROC, SCM_DEFINE and SCM_DEFINE1
macros (through tokens SCM__DR, SCM__DP and SCM__D1, respectively).
See the Guile manual and libguile/snarf.h for details.

By default c2doc uses the C pre-processor determined at Guile
configure time (use "guile-tools guile-config-data CPP" to display
this value).  You can specify an alternative program CPP-PROG using
either the command line option "--cpp CPP-PROG", or by setting the env
var CPP to CPP-PROG (command line option takes precendece).  CPP-PROG
may name either a program or a program and some initial command-line
arguments.  In the latter case, remember to quote CPP-PROG to protect
against shell mishaps.

If the documentation string ends with the sequence:

  \n\n-sig: (SIGNATURE-HINT)

(that is, two newlines, hyphen, #\s, #\i, #\g, colon, space, left
paren, arbitrary non-paren text, and right paren), then SIGNATURE-HINT
is used instead of the signature normally inferred from the req/opt/var
numbers and given C arglist.  This signature hint portion is omitted
from the resulting docstring, as well.  SIGNATURE-HINT can contain
space-separated symbols, square braces and ellipses, for example:
"a b [c [d]] [e f g ...]".


Experimental Feature: Emacs-style doc: comment

Normally, the GH_DEFPROC or SCM_DEFINE form's docstring is encoded
as a series of literal C strings, each ending with a newline.  This
can be somewhat tedious to maintain, so c2doc supports an alternative
syntax, used by Emacs' source code (the parts written in C).  Here
are two GH_DEFPROC macro calls (omitting the GH_DEFPROC) that would
be handled identically by c2doc:

|(foo, "foo", 2, 0, 0,
| (SCM bar, SCM baz),
| "Doc string, first line.\n"
| "More \"information\" here!")

|(foo, "foo", 2, 0, 0,
| (SCM bar, SCM baz),
| doc: /***********
|Doc string, first line.
|More "information" here!  */)

The series of strings in the first block is replaced in the second
block by the token `doc:' followed by a stylized comment.  The text
in the comment no longer needs explicit newlines or any escaping
for double quotes.  On the other hand, the formatting of the token
with respect to the comment start is not flexible; it must match
the regexp " *doc: /[*][^ \n]+".  Note that simply "/*" does NOT
match.  This restriction may be lifted in the future.