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


On 19 May 2000, Keisuke Nishida wrote:

> Another alternative:
> 
> SCM_DEFINE_SCHEME_OBJECT
> SCM_DEFINE_SCHEME_STATIC_OBJECT
> SCM_DEFINE_SCHEME_SYMBOL
> SCM_DEFINE_SCHEME_STATIC_SYMBOL
> SCM_DEFINE_SCHEME_KEYWORD
> SCM_DEFINE_SCHEME_STATIC_KEYWORD
> 
> This is more clear, but a little bit verbose...

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

> After this, the user may write whatever she likes:
> 
> 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.

> > Maybe SCM_DOCUMENT_CONCEPT would also be nice for adding documentation
> > of basic concepts, but not a lot more I think.
> 
> Well, I think simple concepts (e.g., "What is fluid?") can be documented
> with some appropriate procedures (e.g., fluid?).  More complex concepts
> should be documented separately, in my opinion.

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

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.

However, for the time being, it is more important to be able to document
things at all and add at least some initial documentation.  For a lot of
functions, this has already been achieved, and with your suggested
extensions to the snarfer we will get a further large step ahead.

> KN> but I think it is easier for programmers to write C docstrings in
> KN> comment style.  Although those docstrings cannot be parsed by one
> KN> snarf command, we don't want to export C docstrings to Scheme users,
> KN> anyway.
> 
> I mean comment-style C docstrings cannot be parsed at the same time
> as macro-stype Scheme docstrings.  I think this is okay because they
> are different concepts.

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.

Best regards
Dirk


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