This is the mail archive of the guile@sourceware.cygnus.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Suggestion: new snarf macro set


Dirk Herrmann <dirk@ida.ing.tu-bs.de> writes:

> I like it better than the SCM_CREATE_ and SCM_MAKE_ variants.  Maybe some
> other folks from the guile list do also have an opinion on that?  If not,
> I'd say that we take the above solution.  (Although I'm still in doubt
> whether the SCHEME infix is necessary...)

There are only three SCHEME_ macros, so probably defining them simply
without SCHEME_ is okay, too.  Nobody will be confused by that.

> > SCM_SNARF_HERE(static scm_foo);
> > SCM_SNARF_INIT(scm_foo = scm_bar);
> > SCM_SNARF_DOCS("scm_foo", c_variable, "This is foo...");
> 
> I'd like it better if the user would never have to use a SCM_SNARF_ macro,
> no matter what.  But, with the availability of all those SCM_DEFINE_
> macros, there is really little need for additional documentation macros,
> so it is nothing that we have to decide urgently.

The user may define her original macros by using SCM_SNARF_*.
Anyway, I'd define SCM_SNARF_DOCS as above.  We have to distinguish
procedures, syntaxes, variables, and hooks.  (Oh, we can add
SCM_DEFINE_HOOK, too.)

> (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.)

> Documenting simple concepts together with some 'appropriate' procedure is
> the way that it is currently done, but IMO mostly due to the fact that
> there is no other way of doing it yet.  In the long term, I believe that
> we can come to a more sophisticated way of documenting things that for
> example makes use of crossreferencing.  Then, it would be better to be
> able to crossref-reach the 'fluids' concept documentation from _all_
> functions that deal with fluids.

That is right.  We can add "SEE ALSO: @xref{fluid?}" in each docstring,
or we can define a macro SCM_DEFINE_CROSSREFERENCE.  But these things
are extensions, so we can talk about it later.

> Well, I don't think we should differentiate it here.  You are right that
> the duplication of the macro names is not beautiful, but I'd nevertheless
> prefer a common handling and a common documentation data base for
> guile.  Assume you are working in emacs on C code for guile or an
> extension.  Then, you would want to be able to get all the documentation,
> no matter whether for the C or for the scheme level.  At least I wouldn't
> like it if I had to check two different places for documentation.  And if
> we think of a crossref-enabled documentation system, there's a lot of
> potential here:  It would be great if the documentation for null? would
> also point me to scm_nullp and SCM_NULLP, and all of these would point me
> to common descriptions of the concept of lists, cells, etc.

That's a matter of interface, right?  We could still generate a database
from different sources, or even write an interface that uses more than
one databases.

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

----------------------------------------------------------------
;;; Scheme Compact Dictionary

((scd-version . 1)
 (title . "Guile docstrings")
 (index
  ($atan2 . (86478 . 103))
  ($expt . (86376 . 101))
  (%library-dir . (70947 . 220))
  (%make-void-port . (101850 . 323))
  ...
 ))

((name . acons)
 (type . primitive-procedure)
 (file . "$(LIBGUILE)/alist.c:61"))
(acons 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.

((name . sloppy-assq)
 (type . primitive-procedure)
 (file . "$(LIBGUILE)/alist.c:84"))
(sloppy-assq key alist)
Behaves like @code{assq} but does not do any error checking.
Recommended only for use in Guile internals.

...
----------------------------------------------------------------

After this is done, one can easily combine more than one dictionaries
without loosing information.  The only thing we have to do is to write
two scripts: C docstrings -> SCD converter and Scheme docstrings -> SCD
converter.  One may write a C source like this:

----------------------------------------------------------------
SCM_DEFINE_CLASS (scm_class_null, "<null>", ...
"Docstring for <null>.");

SCM_DEFINE_CROSSREFERENCE ("null?", "<null>");
SCM_DEFINE_PROCEDURE (scm_null_p, "null?", ...
"Docstring for null?")
{
  ...
}

/*SCM_DOCS: Docstring for SCM_NULLP. */
/*SCM_XREF: scm_null_p */
#define SCM_NULLP ...
----------------------------------------------------------------

This will generate the following dictionaries:

----------------------------------------------------------------
((scd-version . 1)
 (title . "Guile Scheme docstrings")
 (index
  (<null> . (xxx . xxx))
  (null? . (xxx . xxx))
 ...))

((name . <null>)
 (type . primitive-class))
Docstring for <null>.

((name . null?)
 (c-name . scm_null_p)
 (type . primitive-procedure))
Docstring for null?

...
----------------------------------------------------------------

----------------------------------------------------------------
((scd-version . 1)
 (title . "Guile C docstrings")
 (index
  (SCM_NULLP . (xxx . xxx))
  ...))

((name . SCM_NULLP)
 (type . c-macro)
 (xref . scm_null_p))
Docstring for SCM_NULLP.

...
----------------------------------------------------------------

Then we can write any interface that utilizes these information.
Once the C docstring dictionary is installed, the new describe command
will print like this:

----------------------------------------------------------------
`null?' is a primitive procedure.

Docstring for null?

See Also: <null>, SCM_NULLP
----------------------------------------------------------------

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

Kei

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]