On Fri, Apr 4, 2008 at 7:46 AM, Charles Day <[EMAIL PROTECTED]> wrote:
> On Fri, Apr 4, 2008 at 7:26 AM, Derek Atkins <[EMAIL PROTECTED]> wrote: > > > "Charles Day" <[EMAIL PROTECTED]> 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 > > [EMAIL PROTECTED] PGP key available > > > > _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
