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
pgpk3kqwb5vqT.pgp
Description: signature
_______________________________________________ gnucash-devel mailing list [EMAIL PROTECTED] https://lists.gnucash.org/mailman/listinfo/gnucash-devel
