doxygen-develop

[Doxygen-develop] Re: [Doxygen-users] Making an Easy and fast readable C Library Manual reference.(TODO-Suggestions)

[Dean P. <po...@ds...>]

<snip>

Let me add a big ditto to most of this.  Doxygen is great, but I find it =

is almost, but not quite there for documenting C code.

>2) * hide Macro definitions body. ( and document them like functions )

You can hide macro body with @hideinitializer.  It would be good to be ab=
le to add =

information about the type of macro parameters and expected returns where=
 =

relevant.  Also it would be nice to be able to abstract the fact that a =

macro is a macro and not a function, as sometimes you want to switch =

between functions and macros.

I also tend to want to give the full definition of a struct when =

documenting it instead of the current approach that just lists out the =

members.

I also really want to be able to generate a single HTML/man page per func=
tion =

with a big alphabetic index.  Haven't been able to find a good way to do =

this.
-- =

Dean Povey,              |em: dp...@we...|  JCSI: Java security =
toolkit
Senior S/W Developer     |ph:  +61 7 3864 5120    | uPKI: Embedded/C PKI =
toolkit
Wedgetail Communications |fax: +61 7 3864 1282    |       uASN.1: ASN.1 C=
ompiler
Brisbane, Australia      |www: www.wedgetail.com  | XML Security: XML Sig=
natures =

[Doxygen-develop] Re: [Doxygen-users] Making an Easy and fast readable C Library Manual reference.(TODO-Suggestions)

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

El Mar 20 Nov 2001 06:25, Dean Povey escribi=F3:
> <snip>
>
> Let me add a big ditto to most of this.  Doxygen is great, but I find i=
t
> is almost, but not quite there for documenting C code.
>
> >2) * hide Macro definitions body. ( and document them like functions )
>
> You can hide macro body with @hideinitializer.  It would be good to be =
able

/** \def GSDATAFORMAT_GET_FORMAT_WITHOUT_ENDIANES
*       \hideinitializer
*/

the outputs is....

 #define GSDATAFORMAT_GET_FORMAT_WITHOUT_ENDIANES( __fmt )=20
Value:({ register guint __v;                                          \
         if ( (((__fmt) & FORMAT_BYTEORDER_LE)>>4) ^                    \
              (((__fmt) & FORMAT_BYTEORDER_BE)>>5) )                    \
         __v=3D((__fmt) & ~GSDATAFORMAT_BYTEORDER_MASK);                 =
 \
         else __v=3D(__fmt);                                             =
 \
         __v;                                                           \
         })

I CAN'T HIDE MACRO BODY....=20

> to add information about the type of macro parameters and expected retu=
rns
> where relevant.  Also it would be nice to be able to abstract the fact =
that
> a macro is a macro and not a function, as sometimes you want to switch
> between functions and macros.

The internal designs don't let me do so.

if you see this.

#define GSDATAFORMAT_GET_FORMAT_WITHOUT_ENDIANES( __fmt )=20
	__fmt : a format enum
	macro returns:  the same format without endiantes format info.

you are completely sure that your are using a Macro not a function.


--=20
=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

[Doxygen-develop] Re: [Doxygen-users] Making an Easy and fast readable C Library Manual reference.(TODO-Suggestions)

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

> Let me add a big ditto to most of this.  Doxygen is great, but I find i=
t
> is almost, but not quite there for documenting C code.

I'm agree. But I think not much work is needed to get a better C=20
documentation using doxygen. =20
About Object Oriented C style , I think is not needen because we can work=
 on=20
\defgroup and \addgroup , to get a good doc structure. ( avoiding use the=
=20
\file tag) .

Inheritance structures can be easyly made using \ingroup ( Is what I'm do=
ing).

And I only miss , control on the order of modules or groups.

Y have put the correct order in my INPUT section
but the order in the tree browser is in reverse order (Perhaps a BUG????)

My input section....
------------------------------------
INPUT     =3D        ./src/gsound.h \    <---here  \defgroup Gsound Init
                       ./src/gsmathdefs.h \  <--- here \defgroup Gsound u=
tils
                       ./src/data/gsdata.h \	<--here \gsdata
                       ./src/data/gsdataformat.h \	<--here \GsDataFormat
                      ./src/data/gsdatachannelsys.h \
                      ./src/data/gsdatatimeenv.h \
                      ./src/data/gsdatatime.h \
                      ./src/data/gsdatabuffer.h \
                     ./src/data/gsdatawave.h \
		etc...
		....

This is the output tree browser:
-------------------------------------------
MODULES (browser)

....
Gsound Basics and Tools.=20
	Gsound Constants and utils=20
	Gsound Initialization.  <----First defined and last in the browser
GSound : Basic Data Types=20
	GsDataWave=20
	GsDataBuffer=20
	GsDataTime=20
	GsDataTimeEnv=20
	GsDataChannelSys=20
	GsDataFormat     <----First defined and last in the tree browser
.....
etc
.....
---------------------------------------------

--=20
=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