[sword-devel] Library Doxygen documentation

[Greg Hellings]

Jonathan,

On Sun, Apr 26, 2009 at 2:17 AM, Jonathan Marsden <jmarsden at fastmail.fm> wrote:
> Greg Hellings wrote:
>
>> On Sat, Apr 25, 2009 at 10:55 PM, Greg Hellings <greg.hellings at gmail.com> wrote:
>
>>>> A quick s/GnomeSword/Xiphos/ is probably called for :)
>
>>> That would have to be changed in the SWORD source directly.  All of
>>> that text comes from there.
>
> OK... line 47 of include/swmgr.h
>
> Can someone with SWORD commit privs make that trivial edit, please?
> Since it is a small edit to a comment, it would be hard to argue that it
> is too risky to make the change so close to the 1.6 release :)
>
>>> I can certainly provide you the Doxyfile - it's on the server. License
>>> I don't care about - I'd like for the file to become part of the SWORD
>>> regular distribution, where it would be covered by the GPL or
>>> whatever.
>
> OK.  However, *I* need to care about the licence, if I want to add it to
> a package, either as part of SWORD (if/when it gets accepted into the
> tree), or earlier, if I just add it as part of the packaging process
> myself, which is what I'm thinking of doing for the moment :)
>
> We're deep into Release Candidates for 1.6.0, so in terms of getting
> into the SWORD tree, perhaps this (and associated Makefile.am stuff to
> make use of it) could go into 1.6.1, since it's not a vitally necessary
> change?

Last night Troy added the file to SVN.  Ends up no changes are
necessary for the Makefile.am system, only with his personal script to
create release tarballs.  So from here on out there should be a
Doxyfile included in the release.  I don't know if he added a
Copyright to the file or not.

>
>> P.S. You can find it at http://www.crosswire.org/~ghellings/Doxyfile
>
> Got it, thanks!  You're apparently using an earlier version of doxygen
> than I am, and one config item in there is now obsolete, but doxygen -u
> fixed that for me.  Also, I had to set SHORT_NAMES = YES to work around
> a known issue when using dot under doxygen.

I just used the version of Doxygen that is on the CrossWire server.
Ideally that should be updated to a newer version if there is a
Doxyfile change.  As for the SHORT_NAMES, I don't know exactly what
that is fixing, but submitting a patch for Troy or someone else to
apply to the VCS version of the file should fix the issue.

>
> Other than that, and about 50 warnings (which I'll take a quick look at,
> but probably not tonight), it works for me.

All the warnings I saw were related to missing or incorrectly
documented elements in the source code.  If you see other warnings,
I'm not sure where they came from.

--Greg