[sword-devel] Documentation update

Wed Sep 24 09:52:48 MST 2008

Peter,

On Wed, Sep 24, 2008 at 5:02 AM, Peter von Kaehne <refdoc at gmx.net> wrote:

> Do you think there is enough info there to start creating some man pages?

I presume you mean for the command-line tools in the utilities directory?  I
don't believe any of those really have Doxy-style comments in them.  I do
know that Doxygen is able to create man-style pages, but without Doxy
comments, it won't produce any such files.  If you mean man-style pages of
the class/header references, then that should be as simple as enabling the
option to create the man pages in the Doxyfile, which I can do.  However,
you'd then need to run Doxygen on your own system and install the files
yourself, unless we start including the Doxyfile with the SWORD engine and
adding a make target to build/install the documentation files.

>
>
> I think the usage examples given with the command line options are a bit
> sparse and could do with augmenting. I would be part of that.

The main step would be figuring out how to properly comment a main function
in Doxy-style comments and adding them to the files which lack them (which,
I believe, is all of the CLI tools).  Once you've done that, submit a patch
to the list and someone with SVN commit access will add them to the
repository.  Then we can talk about putting a Doxyfile with the reulgarly
distributed engine and adding the necessary steps to the build process.

--Greg

>
>
> Peter
> -------- Original-Nachricht --------
> > Datum: Tue, 23 Sep 2008 18:17:53 -0500
> > Von: "Greg Hellings" <greg.hellings at gmail.com>
> > An: "SWORD Developers\' Collaboration Forum" <sword-devel at crosswire.org>
> > Betreff: [sword-devel] Documentation update
>
> > List,
> > I've updated the sword-svn documentation kept in
> > http://www.crosswire.org/~ghellings/svnclassdocs/<http://www.crosswire.org/%7Eghellings/svnclassdocs/>to revision 2205 of the
> > SVN tree.
> >
> > I have attached a patch which works out several Doxygen errors/warnings,
> > and
> > the following ones remain.  I did not feel comfortable filling in the
> > missing documentation that these indicate, so I leave it to someone who
> is
> > more familiar with those sections of the code.  Also, if I may have
> > mislabeled the few portions of the code which are in this patch file, so
> > please take care in looking at that.
> >
> > The remaining warnings are as follows:
> >
> > /space/home/ghellings/sword-svn/include/swmgr.h:209: Warning: The
> > following
> > parameters of SWMgr::SWMgr(SWConfig *iconfig=0, SWConfig *isysconfig=0,
> > bool
> > autoload=true, SWFilterMgr *filterMgr=0, bool multiMod=false) are not
> > documented:
> >   parameter 'multiMod'
> > /space/home/ghellings/sword-svn/include/swmgr.h:230: Warning: The
> > following
> > parameters of SWMgr::SWMgr(const char *iConfigPath, bool autoload=true,
> > SWFilterMgr *filterMgr=0, bool multiMod=false, bool augmentHome=true) are
> > not documented:
> >   parameter 'autoload'
> >   parameter 'filterMgr'
> >   parameter 'multiMod'
> >   parameter 'augmentHome'
> >
> > ****Greg's note: these might represent different naming schemes between
> > the
> > header and the implementation file - but I'm not certain about that****
> > /space/home/ghellings/sword-svn/src/mgr/stringmgr.cpp:216: Warning:
> > argument
> > 'text' of command @param is not found in the argument list of
> > StringMgr::upperLatin1(char *buf, unsigned int maxlen=0) const
> > /space/home/ghellings/sword-svn/src/mgr/stringmgr.cpp:216: Warning:
> > argument
> > 'max' of command @param is not found in the argument list of
> > StringMgr::upperLatin1(char *buf, unsigned int maxlen=0) const
> > /space/home/ghellings/sword-svn/src/mgr/stringmgr.cpp:216: Warning:
> > argument
> > 'The' of command @param is not found in the argument list of
> > StringMgr::upperLatin1(char *buf, unsigned int maxlen=0) const
> > /space/home/ghellings/sword-svn/src/mgr/stringmgr.cpp:216: Warning: The
> > following parameters of StringMgr::upperLatin1(char *buf, unsigned int
> > maxlen=0) const are not documented:
> >   parameter 'buf'
> >   parameter 'maxlen'
> > /space/home/ghellings/sword-svn/src/mgr/stringmgr.cpp:180: Warning:
> > argument
> > 'text' of command @param is not found in the argument list of
> > StringMgr::upperUTF8(char *t, unsigned int maxlen=0) const
> > /space/home/ghellings/sword-svn/src/mgr/stringmgr.cpp:180: Warning:
> > argument
> > 'max' of command @param is not found in the argument list of
> > StringMgr::upperUTF8(char *t, unsigned int maxlen=0) const
> > /space/home/ghellings/sword-svn/src/mgr/stringmgr.cpp:180: Warning: The
> > following parameters of StringMgr::upperUTF8(char *t, unsigned int
> > maxlen=0)
> > const are not documented:
> >   parameter 'maxlen'
> >
> > /space/home/ghellings/sword-svn/include/listkey.h:81: Warning: The
> > following
> > parameters of ListKey::SetToElement(int ielement, SW_POSITION pos=TOP)
> are
> > not documented:
> >   parameter 'pos'
> >
> > /space/home/ghellings/sword-svn/src/modules/swmodule.cpp:1248: Warning:
> no
> > matching class member found for
> >   void SWModule::filterBuffer(std::list< SWOptionFilter * > *filters,
> > SWBuf
> > &buf, SWKey *key)
> > Possible candidates:
> >   virtual void SWModule::filterBuffer(OptionFilterList *filters, SWBuf
> > &buf,
> > SWKey *key)
> >   virtual void SWModule::filterBuffer(FilterList *filters, SWBuf &buf,
> > SWKey
> > *key)
> > /space/home/ghellings/sword-svn/src/modules/swmodule.cpp:1260: Warning:
> no
> > matching class member found for
> >   void SWModule::filterBuffer(std::list< SWFilter * > *filters, SWBuf
> > &buf,
> > SWKey *key)
> > Possible candidates:
> >   virtual void SWModule::filterBuffer(OptionFilterList *filters, SWBuf
> > &buf,
> > SWKey *key)
> >   virtual void SWModule::filterBuffer(FilterList *filters, SWBuf &buf,
> > SWKey
> > *key)
> > /space/home/ghellings/sword-svn/include/apocrypha.h:212: Warning:
> > documented
> > function `long VerseKey::atbks' was not declared or defined.
> > /space/home/ghellings/sword-svn/include/apocrypha.h:217: Warning:
> > documented
> > function `long VerseKey::atcps' was not declared or defined.
> >
> > Once again, feedback on the documentation configuration is appreciated if
> > you find something missing or too much present, etc, or if you have
> > expertise with Doxygen (because I sure don't).
> >
> > --Greg
>
> --
> GMX startet ShortView.de. Hier findest Du Leute mit Deinen Interessen!
> Jetzt dabei sein:
> http://www.shortview.de/wasistshortview.php?mc=sv_ext_mf@gmx
>
> _______________________________________________
> sword-devel mailing list: sword-devel at crosswire.org
> http://www.crosswire.org/mailman/listinfo/sword-devel
> Instructions to unsubscribe/change your settings at above page
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.crosswire.org/pipermail/sword-devel/attachments/20080924/dffcff13/attachment-0001.html 