QOF merge code ready

Neil Williams linux at codehelp.co.uk
Thu Aug 26 18:20:42 EDT 2004


On Thursday 26 August 2004 5:13, Linas Vepstas wrote:
> Looks good to me.
> 
> Check it in ... 
> This is going into the qof.sourceforge.net cvs.   If its not too
> much trouble, make a corresponding patch for gnucash.org

The GnuCash patch is on it's way.

> One minor comment:
>
> Carefule with adding documetnation like this:
> > +/** QofIdType declaration */
> >  typedef const char * QofIdType;
> > +/** QofIdTypeConst declaration */
> >  typedef const char * QofIdTypeConst;

This is just a linkage aid for doxygen. It allows doxygen to make a link from 
any QofIdType variable to the QofIdType declaration. I found it extremely 
useful in understanding QOF. Without it, the private header files are not 
fully linked and structs and typedefs, particularly these four, are hidden 
and obscure.

QofIdType (and the Const version)
QofEntity
QofParam
QofCollection

e.g. here:
http://www.codehelp.co.uk/doxygen/group__BookMerge.html#ga3
char* qof_book_merge_param_as_string ( QofParam * qtparam, 
QofEntity * qtEnt ) 

In my local doxygen output FTP'd to codehelp, as patched, the word QofParam is 
automatically linked to 
http://www.codehelp.co.uk/doxygen/struct__QofParam.html
and QofEntity is linked to 
http://www.codehelp.co.uk/doxygen/structQofEntity__s.html

In the unpatched QOF and GnuCash doxygen pages, these two are simple text with 
no links, no matter where QofParam or QofEntity variables are used in 
functions.

Doxygen automatically takes care of linking every incidence of every 
recognised struct or typedef across the entire doxygen output. It works for 
so many other areas and with the patch it works for these as well.

> This doesn't seem to contain any information that isn't already in the
> C code.  i.e. just reading teh C code will tell you everything here

It does duplicate some info, however, I found it useful to have the 
declarations in the doxygen pages because when you are simply faced with 
QofEntity *importEnt;, it isn't immediately obvious WHICH file contains the 
actual struct definition. So it means I have to grep for it and then load the 
file into an already crowded IDE and search for the definition. With these 
small adjustments, doxygen does the entire task in one operation - and 
without having to switch applications.

I had to learn QOF from the outside (and I'm still learning) and IMHO not 
having all struct definitions available to doxygen made it more difficult 
than it could have been.

In the case of qofid.h, it's not the information that I've added that matters 
to me, it's the link that doxygen creates from that information.

It's a way of easing new developers into the flow whilst still retaining 
private header files that doxygen doesn't quite handle.

> already.  So I'm not to thrilled with this, it just clutters things
> up needlessly, wihtout adding value.  Something better may have been:

I hope you can see that the value comes from the final doxygen conversion, at 
least, it does for me.

> 'is_dirty is a boolean flag that, when set indicates that the object
> has been modified but has not yet been saved to disk.'  That's
> something you wouldn't get by reading the header file.

OK.

> Let this one slide, but in general don't do this unless there's
> real true value add.

I've made amendments to my local copies of the business object header files in 
the same manner. I'll omit these from any patches I send in unless I hear 
from you or Derek, but they do make working with the business objects much 
easier for me. It means I can more easily retain a train of thought across 
various objects and in a single view / single tool.

Maintaining all these separate CVS trees is getting awkward! I've got one for 
current work (which may or may not compile at a specific time) and which I 
never use against makepatch, then there is a pristine copy of HEAD which is 
'read-only' and  forms the basis of the makepatch comparison, a devel copy of 
HEAD that has the files I want to update (but only those files) copied into 
it, ready for makepatch and finally a copy of devel that I use to make sure 
the amended tree builds after I've copied the new or amended files into devel 
and before I run makepatch. That's without my gnucash gnome2 and QOF trees!
It's not filespace that concerns me (I've got 6.5G for /opt) just the number 
of copies.

> --linas

P.S. Could the doxygen pages on the QOF sourceforge homepages be updated? If 
it's something I can do via SSH, just drop me a line and I'll keep it 
updated.
http://qof.sourceforge.net/doxy/index.html
QOF design and developer's reference  0.4.2 

-- 

Neil Williams
=============
http://www.codehelp.co.uk/
http://www.dclug.org.uk/
http://www.isbn.org.uk/
http://sourceforge.net/projects/isbnsearch/

http://www.biglumber.com/x/web?qs=0x8801094A28BCB3E3
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: signature
Url : http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20040826/80e45227/attachment.bin


More information about the gnucash-devel mailing list