OK to add swigified function to core-utils?

[Charles Day]

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.

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