doxygen-users

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

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

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

Hi,

(the topic is rather old, anyway...)

Carlo Wood wrote:
> On Tue, Nov 20, 2001 at 11:08:03AM +0100, Prikryl,Petr wrote:
> > 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.
> 
> Make the default behaviour configurable and allow to toggle
> the behaviour per enum with some command.  The is no reason
> not to do that, and there clearly exist the need for this
> with some users.

Yes, I basically agree with enhancements.  On the other hand,
there are some reasons for not adding every possible option to the
configuration file.  Firstly, the more options you have, the more
difficult is to set them correctly.  Secondly--what is probably even
more important--, the more options you have, the more difficult
is to keep the program (doxygen) clear and correct (i.e. bug-free).

To summarize: we can discuss about it, but the ideas should be
very clear before they are to be implemented.

Regards,
  Petr

-- 
Petr Prikryl, Skil, spol. s r.o., (pri...@sk...)

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

[Carlo W. <ca...@al...>]

On Tue, Nov 20, 2001 at 11:08:03AM +0100, Prikryl,Petr wrote:
> 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.

Make the default behaviour configurable and allow to toggle
the behaviour per enum with some command.  The is no reason
not to do that, and there clearly exist the need for this
with some users.

-- 
Carlo Wood <ca...@al...>