doxygen-users

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

[Toni M. <ton...@wa...>]

> >C) Enums:
> >  I asign a value to all "labels" in my enums.
> >
> >         Example:
> >
> >         enum MyEnum {
> >                 MYVAL_0 =3D 0,
> >                 MYVAL_1 =3D 3,
> >                 MYVAL_2 =3D 0x08,
> >         }
> >
> >The doxigen outputs , maintains the values, but I would like only show=
ing
> >
> >         enum MyEnum {
> >                 MYVAL_0,
> >                 MYVAL_1,
> >                 MYVAL_2,
> >         }
> >
> I'm not sure why you think you need the features, but
> A) turn of include source... we generate two versions, for users and fo=
r
> developers... users don't get the source
> C) knowing the name of an enum withOUT it's value is barely useful whil=
e
> debugging.

See yourself.


typedef enum  GsDataFormat {=20
  GSDATAFORMAT_SI8 =3D=20
GSDATAFORMAT_SET_INT(FORMAT_SIGNED,FORMAT_BYTEORDER_NE,1),=20
  GSDATAFORMAT_SI16 =3D=20
GSDATAFORMAT_SET_INT (FORMAT_SIGNED, FORMAT_BYTEORDER_HE, 2),=20
  GSDATAFORMAT_SI16_LE =3D=20
GSDATAFORMAT_SET_INT (FORMAT_SIGNED, FORMAT_BYTEORDER_LE, 2),=20
  GSDATAFORMAT_SI16_BE =3D=20
GSDATAFORMAT_SET_INT (FORMAT_SIGNED, FORMAT_BYTEORDER_BE, 2),=20
  GSDATAFORMAT_SI32 =3D=20
GSDATAFORMAT_SET_INT (FORMAT_SIGNED, FORMAT_BYTEORDER_HE, 4) ,=20
  GSDATAFORMAT_SI32_BE =3D=20
GSDATAFORMAT_SET_INT (FORMAT_SIGNED, FORMAT_BYTEORDER_BE, 4),=20
  GSDATAFORMAT_UI8 =3D=20
GSDATAFORMAT_SET_INT (FORMAT_UNSIGNED, FORMAT_BYTEORDER_NE, 1),=20
  GSDATAFORMAT_UI16 =3D=20
GSDATAFORMAT_SET_INT (FORMAT_UNSIGNED, FORMAT_BYTEORDER_HE, 2),=20
  GSDATAFORMAT_UI16_LE =3D=20
GSDATAFORMAT_SET_INT (FORMAT_UNSIGNED, FORMAT_BYTEORDER_LE, 2),=20
  GSDATAFORMAT_UI16_BE =3D=20
GSDATAFORMAT_SET_INT (FORMAT_UNSIGNED, FORMAT_BYTEORDER_BE, 2),=20
  GSDATAFORMAT_UI32 =3D=20
GSDATAFORMAT_SET_INT (FORMAT_UNSIGNED, FORMAT_BYTEORDER_HE, 4),=20
  GSDATAFORMAT_UI32_LE =3D=20
GSDATAFORMAT_SET_INT (FORMAT_UNSIGNED, FORMAT_BYTEORDER_LE, 4),=20
  GSDATAFORMAT_UI32_BE =3D=20
GSDATAFORMAT_SET_INT (FORMAT_UNSIGNED, FORMAT_BYTEORDER_BE, 4),=20
  GSDATAFORMAT_NF32 =3D=20
GSDATAFORMAT_SET_FP (FORMAT_FPNORM, FORMAT_BYTEORDER_HE, 4),=20
  GSDATAFORMAT_NF32_LE =3D=20
GSDATAFORMAT_SET_FP (FORMAT_FPNORM, FORMAT_BYTEORDER_LE, 4),=20
  GSDATAFORMAT_NF32_BE =3D=20
GSDATAFORMAT_SET_FP (FORMAT_FPNORM, FORMAT_BYTEORDER_BE, 4),=20
  GSDATAFORMAT_NF64 =3D=20
GSDATAFORMAT_SET_FP (FORMAT_FPNORM, FORMAT_BYTEORDER_HE, 8),=20
  GSDATAFORMAT_NF64_LE =3D=20
GSDATAFORMAT_SET_FP (FORMAT_FPNORM, FORMAT_BYTEORDER_LE, 8),=20
  GSDATAFORMAT_NF64_BE =3D=20
GSDATAFORMAT_SET_FP (FORMAT_FPNORM, FORMAT_BYTEORDER_BE, 8)=20
 }

where GSDATAFORMAT_SET_{INT.FP} () is a macro that defines data types. on=
ly=20
used in development of the library.

do You really think  can be usefull maintain values?

 library users need  ONLY. to know the label of each format type.

typedef enum  GsDataFormat {=20
  GSDATAFORMAT_SI8 ,	/** and some other comment about..*
  GSDATAFORMAT_SI16,
  GSDATAFORMAT_SI16_LE,
  GSDATAFORMAT_SI16_BE,=20
  GSDATAFORMAT_SI32,
  GSDATAFORMAT_SI32_BE,
  GSDATAFORMAT_UI8,
  GSDATAFORMAT_UI16,
  GSDATAFORMAT_UI16_LE,
  GSDATAFORMAT_UI16_BE,
  GSDATAFORMAT_UI32,
  GSDATAFORMAT_UI32_LE,
  GSDATAFORMAT_UI32_BE,
  GSDATAFORMAT_NF32,
  GSDATAFORMAT_NF32_LE,
  GSDATAFORMAT_NF32_BE,=20
  GSDATAFORMAT_NF64,
  GSDATAFORMAT_NF64_LE,
  GSDATAFORMAT_NF64_BE,=20
 }

-------------------------------------------

ABOUT DEFINES

this is the output of a Macro generated by doxygen.

 #define GS_UI32_TO_SI32( __v )    ( (gint32) ((__v)+GS_DC_INT32))=20
	Returns: This macro return the (gint32) converted value=20

How can I show only ..?:

#define GS_UI32_TO_SI32( __v ) =20
	Returns: This macro return the (gint32) converted value=20



Thanks.

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
Toni Moreno Gim=E9nez
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
Pje de las rosas  n=BA 22
Vilassar de Mar=20
(Barcelona) Espa=F1a
CP: 08340

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

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

On Mon, Nov 19, 2001 at 06:27:04PM +0100, Toni Moreno Giménez wrote:
> library users need  ONLY. to know the label of each format type.

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.
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).

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

/**
 * \show_values
 */
enum foo {
...

Same thing for macro functions, in general the definition of
the macro should be hidden and only shown when explicitely
requested:

/**
 * \show_definition
 */
#define FOO(x) (x * x * x - 2 * x + 3)

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

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

[Johan E. <joh...@ua...>]

Hi guys,
            has anyone tested the configuration option=20
MAX_INITIALIZER_LINES, I did that for enums by setting it to zero and=20
then the value disappeared......I don't know if this solves your=20
problems with different defines, enums, etc. but to introduce another=20
command like \show_values, \show_definition seems to be overkill since=20
it already exists the commands \showinitializer and \hideinitializer......

In general, I think it is good to provide different options to customize=20
e.g. a tool. However, when/if the options starts to depend on each in=20
one way or another, the complexibility to maintain and test the=20
different combinations increases (exponential?) especially as for a tool=20
like Doxygen where a number of output formats is also provided....

I think for Doxygen, it provides a lot of options already and adding new=20
options should be considerred very carefully (which I am sure of is done=20
by Dimitri) and instead concentrate of developing the tool with=20
increased functionality like e.g. the xml parser.

Just some thoughts,
                             Johan

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.
>>
>
>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.
>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).
>
>The default should be NOT to show enum values.  An option
>*per* enum could be added to show it.  For example:
>
>/**
> * \show_values
> */
>enum foo {
>...
>
>Same thing for macro functions, in general the definition of
>the macro should be hidden and only shown when explicitely
>requested:
>
>/**
> * \show_definition
> */
>#define FOO(x) (x * x * x - 2 * x + 3)
>