Thread: Re: [Doxygen-users] Making an Easy and fast readable C Library Manual reference.(TODO-Suggestions)
Brought to you by:
dimitri
Menu
▾
▴
doxygen-users
|
From: Dean P. <po...@ds...> - 2001-11-20 05:25:28
|
<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 = |
|
From: Toni M. <ton...@wa...> - 2001-11-20 17:51:25
|
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
|
|
From: Dimitri v. H. <di...@st...> - 2001-11-20 19:49:15
|
On Tue, Nov 20, 2001 at 07:05:56PM +0100, Toni Moreno Giménez wrote:
> El Mar 20 Nov 2001 06:25, Dean Povey escribió:
> > <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 able
>
> /** \def GSDATAFORMAT_GET_FORMAT_WITHOUT_ENDIANES
> * \hideinitializer
> */
>
> the outputs is....
>
> #define GSDATAFORMAT_GET_FORMAT_WITHOUT_ENDIANES( __fmt )
> Value:({ register guint __v; \
> if ( (((__fmt) & FORMAT_BYTEORDER_LE)>>4) ^ \
> (((__fmt) & FORMAT_BYTEORDER_BE)>>5) ) \
> __v=((__fmt) & ~GSDATAFORMAT_BYTEORDER_MASK); \
> else __v=(__fmt); \
> __v; \
> })
>
> I CAN'T HIDE MACRO BODY....
Then you are doing something wrong!
Using:
/** \file */
/** Docs here.
* \hideinitializer
*/
#define GSDATAFORMAT_GET_FORMAT_WITHOUT_ENDIANES( __fmt ) \
({ register guint __v; \
if ( (((__fmt) & FORMAT_BYTEORDER_LE)>>4) ^ \
(((__fmt) & FORMAT_BYTEORDER_BE)>>5) ) \
__v=((__fmt) & ~GSDATAFORMAT_BYTEORDER_MASK); \
else __v=(__fmt); \
__v; \
})
/*! An enum */
typedef enum
{
val = 10 /*!< \hideinitializer enum value */
} MyEnum;
With a default config file, I get no initializer for defines or enums.
If you get tired of typing \hideinitializer, then set
MAX_INITIALIZER_LINES to 0 to hide all initializers
automatically and use \showinitializer at those place
where values are needed.
Regards,
Dimitri
|
|
From: Toni M. <ton...@wa...> - 2001-11-21 03:55:12
Attachments:
DOXYFILE
gsdatachannelsys.h
|
> > I CAN'T HIDE MACRO BODY....
>
> Then you are doing something wrong!
>
> Using:
>
> /** \file */
>
> /** Docs here.
> * \hideinitializer
> */
> #define GSDATAFORMAT_GET_FORMAT_WITHOUT_ENDIANES( __fmt ) \
> ({ 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; \
> })
>
> /*! An enum */
> typedef enum
> {
> val =3D 10 /*!< \hideinitializer enum value */
> } MyEnum;
>
> With a default config file, I get no initializer for defines or enums.
The enums runs OK thanks...
But i can't hide macros.
I have tested 4 ways.
1) ----------------------------------------
/** \def GSDATACHANNELSYS_GET_NUMCH
* Gets the number of channels
*=09
*/
#define GSDATACHANNELSYS_GET_NUMCH(__chsys)\
((__chsys) & GSDATACHANNELSYS_NUMCH_MASK)
2) ----------------------------------------
/** \def GSDATACHANNELSYS_GET_NUMCH
* Gets the number of channels
* \hideinitializer=09
*/
#define GSDATACHANNELSYS_GET_NUMCH(__chsys)\
((__chsys) & GSDATACHANNELSYS_NUMCH_MASK)
3) ------------------------------------------
/** \def GSDATACHANNELSYS_GET_NUMCH
* Gets the number of channels
*
*/
#define GSDATACHANNELSYS_GET_NUMCH(__chsys)\
(\
((__chsys) & GSDATACHANNELSYS_NUMCH_MASK)\
)
4) ------------------------------------------
/** \def GSDATACHANNELSYS_GET_NUMCH
* Gets the number of channels
* \hideinitializer
*/
#define GSDATACHANNELSYS_GET_NUMCH(__chsys)\
(\
((__chsys) & GSDATACHANNELSYS_NUMCH_MASK)\
)
--------------------------------------------
The Html Output for 3 and 4 cases are "exactly" the same independent of =
the=20
\hideinitializer tag
In 3 and 4 cases the DEFINES section dont show the body of the macro but
the DEFINES DOCUMENTATIONS section continues showing it.
The output for 1 and 2 cases are "exactly" the same independent of the=20
\hideinitializer tag. Where the html ouput shows body macro in both secti=
ons
DEFINES section and DEFINES DOCUMENTATION section.
Perhaps I'm doing something wrong but i can't solve it.
I have atached , my config file and a header source code for testing your=
self.
=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
-----------------
Tel:937598149
Tel: 699706656
----------------- |
|
From: Toni M. <ton...@wa...> - 2001-11-20 18:32:47
|
> 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
|
Thanks for helping keep SourceForge clean.
X