OK to add swigified function to core-utils?

[Charles Day]

On Thu, Apr 3, 2008 at 8:38 AM, Derek Atkins <warlord at mit.edu> wrote:

> "Charles Day" <cedayiv at gmail.com> writes:
>
> > I've now committed the changes to fix bug 396665 as r17063. In doing so,
> I
> > created a Scheme predicate named "gnc-utf8?" using SWIG. It would be
> nice to
> > document the existence of this new Scheme predicate for other
> developers.
> > Does anyone know if I can just add doxygen-style comments to the SWIG .i
> > file? Will that cause the documentation of this function to appear at
> > http://svn.gnucash.org/docs/HEAD/?
>
> 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.

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?".

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

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