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