RE: [Doxygen-users] Documenting a "libray reference Manual" using Doxygen.

[Prikryl,Petr <PRI...@sk...>]

Hi Carlo and other doxygeners,

Carlo Wood wrote...
> On Mon, Nov 19, 2001 at 06:27:04PM +0100, Toni Moreno Gim=E9nez =
wrote:
> > library users need  ONLY. to know the label of each format type.
>=20
> I agree.  The nature of enums is such that in general the value
> is 'internal', and showing it to a user messes up the cleanness
> of the documentation as it is not relevant.

I think that it is not the case of C/C++.  If one does need any
conversion, then he/she should not assign the explicit values.
If explicit values are assigned to the items, then they are probably=20
intended to be used for conversions to integer types, and this=20
should be visible.  Doxygen shows only explicitly stated values.=20

> In SOME cases it is important to know the values, when enums
> are correlated somehow, but that is in general Bad Programming
> then (and constant integers should have been used instead).

I also think that using enums without explicit values is somehow
cleaner.  But if you need to assign the enum item the explicit value,
then you should know why.  In other words, if you assign the enum
constants the explicit values and you don't need the explicit values,
then it is a bad programming practice.  But if you really need that,
then the situation should be made visible.

> The default should be NOT to show enum values.  An option
> *per* enum could be added to show it.

In the context of my previous comments, I disagree with hiding
explicitly stated values of enum items as the default behaviour.
I even think that nothing should be changed.

(Note: Toni Moreno Gim=E9nez uses enum with values defined this way.)
> > typedef enum  GsDataFormat {=20
> >   GSDATAFORMAT_SI8 =3D=20
> > GSDATAFORMAT_SET_INT(FORMAT_SIGNED,FORMAT_BYTEORDER_NE,1),=20
> > [...]
> > }

Toni should use some different (possibly non automatic) kind of =
documenting
such enum values).

Your opinion?
  Petr