OK to add swigified function to core-utils?
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
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
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.
> > 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