Re: Suggestion: new snarf macro set

[Dirk Herrmann <dirk at ida dot ing dot tu-bs dot de>]

On 19 May 2000, Keisuke Nishida wrote:

> Dirk Herrmann <dirk@ida.ing.tu-bs.de> writes:
> 
> > (With 'but not a lot more' I didn't mean that SCM_DOCUMENT_CONCEPT was
> > only suitable to document simple (basic) concepts, but I rather meant that
> > we don't need a lot more additional documentation macros than
> > SCM_DOCUMENT_C_MACRO and SCM_DOCUMENT_CONCEPT.  Sorry for the confusion.)
> 
> (We need at least SCM_DOCUMENT_C_FUNCTION and SCM_DOCUMENT_C_VARIABLE,
> by the way.  We'd like to document scm_c_* as well.)

Maybe I'm missing something, but if you'd define SCM_DEFINE_C_FUNCTION as:

#define SCM_DEFINE_C_FUNCTION(RTYPE, FNAME, ARGLIST, DOCSTRING) \
SCM_HERE ( \
RTYPE FNAME ARGLIST \
) \
SCM_DOCS ( \
<formatted docstring goes here>
))

you would have the same combined documentation/definition possibilities as
for primitives.  C variables can be declared in a similar way.  It's just
macros that can not be defined within macros.

> I have designed a simple dictionary format for general use.  With my
> special snarf script, the Guile's docstrings are converted like this:

Pretty cool.

> So, there is no drawback with comment-style docstrings.

You are right, and after checking the guile archive for the discussion
about adding documentation to guile, it seems that while SCWM dropped the
comment-style docstrings for functions, they kept them for describing
concepts.  (Guile's current documentation macros are an adaption of 
SCWM's macros.)  Greg Badros could probably give some better informed
comments on the issue.

Best regards,
Dirk