enum values to strings.

[Derek Atkins]

Neil Williams <linux at codehelp.co.uk> writes:

> On Thursday 24 March 2005 9:41 pm, Derek Atkins wrote:
>> Note that in many cases this conversion is already done. The Gnucash XML 
>> does this in most cases.  Take a look at, e.g. src/engine/Account.c for an
>> example. It's not _quite_ as clever as your code, but it does the job.
>
> (I wish that had been documented with Doxygen!) I knew it had to exist, just 
> couldn't find it!

You could've asked. ;)

> AFAICT, the advantage is:
> The larger macro removes the need to have two separate functions in tandem. 
> Only the ENUM_LIST needs to be edited to add or remove values - it's more 
> like the underlying enum itself. That should make for easier changes in 
> future.

The number of times these enums change is relatively low.  The added
overhead in these enums is relatively high.  Also, there are
definitely source files where we have multiple enums.

Moreover, as you mention, it confuses the compiler and doxygen.  In
places where you want the enum public but the functions private,
you've effectively published the source code for the enum translators
in the header.  Either that or you need to duplicate the enum
definition (define the list in the header, define the functions in the
.c file).  However that would seem to be counter to your argument
about duplicating the list.

[snip]
> Is that workable? Is it worth using it *in place of* the existing macros to 
> ease future development? Use just for enums not already covered?

I would say just do what we're already doing.  I don't think it really
saves a tremendous amount of work.  It's not like we're talking about
dozens of enums with hundreds of members.  Moreover, MOST of the
existing enums already have translations!  You just need to hook them
into QOF.

> Why, in Account.c, are the current macros undefined after the function 
> declaration? I was thinking of defining the main macros just once in one of 
> the header files in /src/engine - are there issues with scoping / duplicates 
> that can't be resolved as you would normally with header files?

Um, I dont know.  For cleanliness?  Technically I suppose there's no
reason they need to be undefined after they're used.

> Only the ENUM_LIST macro would be defined in the main source, once per enum. 
> (It doesn't have to be called ENUM_LIST either if that's a problem, each enum 
> can have their own.)

Except you still need to define the enum list in the HEADER, not the
.c file!

> The only drawback that I've found so far:
> Doxygen needs the values to be repeated if you are going to document the enum 
> values. Currently Doxygen documents the ENUM_LIST define not the enum and the 
> macro removes any /**< */ constructs.

That's a MAJOR drawback.  We really want to document the enums; most
of them are public parts of the API, and some have very subtle
connotions that should be part of the docs.

>> And yes, we should definitely be using strings instead of ints for enums.
>> Remember when I asked why you needed QOF_TYPE_INT32?  ;)
>
> Yes, I do. 
> :-)

See, this is why.  IMHO any "QOF_TYPE_INT32" really implies
"QOF_TYPE_ENUM".  I thought I had mentioned that the first time
around, but I guess it didn't make sense until now.  Oh well, live and
learn (from both sides).

-derek

-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available