OK to add swigified function to core-utils?

[Derek Atkins]

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

> 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