OK to add swigified function to core-utils?

Charles Day cedayiv at gmail.com
Tue Apr 8 01:01:37 EDT 2008


On Fri, Apr 4, 2008 at 7:46 AM, Charles Day <cedayiv at gmail.com> wrote:

> On Fri, Apr 4, 2008 at 7:26 AM, Derek Atkins <warlord at mit.edu> wrote:
>
> > "Charles Day" <cedayiv at gmail.com> writes:
> >
> > >     That's a very good question, and I'm afraid I don't know the
> > answer.
> > >     You're certainly welcome to update the doxygen.conf.in as
> > necessary
> > >     to get it to work.  I think that doxygenizing the Scheme API would
> > be
> > >     excellent!
> > >
> > > I did some quick research and it looks to me like doxygen doesn't
> > understand
> > > SWIG .i files. In any case, I would think that we would want to
> > document how
> > > the functions would actually look and be called in Scheme, which
> > doxygen
> > > doesn't understand.
> >
> > True.  HOWEVER it does look like swig has some built-in documentation
> > capabilities.  (See <http://www.swig.org/Doc1.1/HTML/Documentation.html>
> > )
> > According to that we can generate HTML documentation (although it
> > doesn't look QUITE as nice as doxygen)
> >
>
> Cool. This looks promising. I'm going to play with it and see what
> happens.
>

It turns out that for what you are talking about, you have to go back to
SWIG 1.1 (and some people do just that, purely for documentation-generation
purposes).

It seems that SWIG 1.3 cannot produce HTML documentation. SWIG now only
generates Guile-specific documentation files of the form required by the
(ice-9 documentation) module. This would be fine if Guile (or some other
utility) could then generate usable documentation from that, but I haven't
found anything that fits the bill.

-Charles


> -Charles
>
> > We could make a separate .txt file that documents the results of
> > > swigification, though. For example, to go with core-utils.i we could
> > create a
> > > file named core-utils.i.txt that documents how to call the swigified
> > functions
> > > from Scheme. But at that point we are in effect just maintaining
> > documentation
> > > independently from code. And for most swigified functions, the main
> > difference
> > > between Scheme and C is just the name (e.g. gnc_locale_from_utf8
> > becomes
> > > gnc-locale-from-utf8).  I would think that only in very special cases
> > would we
> > > be creating brand new functions with SWIG, such as my Scheme predicate
> > > "gnc-utf8?".
> >
> > Right, we should have SWIG generate that .txt file.  Or better yet
> > have it generate a set of .html files as part of the "make doc"
> > directive.
> >
> > > Do you think that I should just add some documentation for the
> > SWIG-generated
> > > Scheme predicate "gnc-utf8?" as part of the description for its C
> > counterpart,
> > > gnc_utf8_validate()? For example, I could add the following: "The
> > > gnc_utf8_validate() function may be called from Scheme by using the
> > gnc-utf8?
> > > predicate. For example, (gnc-utf8? mystring) evaluates to #t if
> > mystring is
> > > UTF-8 encoded, and #f otherwise."
> >
> > No, I don't think so.  I don't think the scheme wrapper information
> > should
> > be in the C information.
> >
> > > -Charles
> >
> > -derek
> > --
> >       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
> >       Member, MIT Student Information Processing Board  (SIPB)
> >       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
> >       warlord at MIT.EDU                        PGP key available
> >
>
>


More information about the gnucash-devel mailing list