doxygen-develop

[Doxygen-develop] doxygen preprocessor, not always expands

[Stefan K. <ko...@im...>]

hi dimitri and others,

I am using Doxygen version 1.3.3.
In the documentation of a C based project I have the following situation :

=== header1.h

struct GitkWidget {
#define GitkWidgetFields \
  gchar *id; /**< @brief string identification */\
  GitkContextPtr context; /**< @brief context the widget belongs to */\
  GitkWidgetType type /**< @brief what kind of widget is it */
  GitkWidgetFields;
};

=== header2.h

#include "header1.h"
struct GitkrGtkWidget {
  GitkWidgetFields;
  GtkWidget *impl; /**< @brief the widget implementation */
};

=== Doxyfile

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = NO
SEARCH_INCLUDES        = YES
SKIP_FUNCTION_MACROS   = YES

===

=== Problem 1:
when running doxygen it expands the macro there, but complains about
undocumented variables. Are the documentes inside the define dropped?

header1.h:6:Warning: Member id of class GitkWidget is not documented.
header1.h:6:Warning: Member context of class GitkWidget is not documented.
header1.h:6:Warning: Member type of class GitkWidget is not documented.

=== Problem 2:
it does not expand the define in the second header file. Both, the data-fields
list and the graph are missing the 'inherited' elements.

header2.h:3:Warning: Member GitkWidgetFields of class GitkrGtkWidget is not
documented.

===

Anyway, does anyone has a better idea, of how to do 'inheritance' in C (not
C++). Unfortunately I am bound to use gcc 2.95 and this one does not support
anonymous structs/unions.
Wouldn't it be a good idea to have a @extends command (which should not be used
in C++/Java) so that I call documents such relations even in C.

Ciao
  Stefan
-- 
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
|      ///           04277 Leipzig      04251 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -

Re: [Doxygen-develop] doxygen preprocessor, not always expands

[Stefan K. <ko...@im...>]

Hi Sigmund,

was the patch denied or ignored. Maybe should should you should bug dimitri to
pay attantion to it again. Unfortunately I get thousands of diffenrences when
comparing doxygen 1.3.5 (to which I just have upgraded). So I am not sure, what
and how much you actually have changed.

Dimitri: are you aware of the problem? Can you please comment on it.

Ciao
  Stefan

> I sent a patch to fix this kind of problem a while ago, but it never got
> accepted. If you want you can try my patched version at
> ftp://ftp.videolan.org/pub/videolan/devtools/doxygen-vlcpatched.tgz
> (it is getting a bit old now)
> I hope a future version of doxygen whould include such a fix, since I don't
> feel like maintaining a paralell tree.
> 
> Sigmund Augdal
> 
> 
> On Mon, Dec 08, 2003 at 01:36:30PM +0100, Stefan Kost wrote:
> 
>>hi dimitri and others,
>>
>>I am using Doxygen version 1.3.3.
>>In the documentation of a C based project I have the following situation :
>>
>>=== header1.h
>>
>>struct GitkWidget {
>>#define GitkWidgetFields \
>>  gchar *id; /**< @brief string identification */\
>>  GitkContextPtr context; /**< @brief context the widget belongs to */\
>>  GitkWidgetType type /**< @brief what kind of widget is it */
>>  GitkWidgetFields;
>>};
>>
>>=== header2.h
>>
>>#include "header1.h"
>>struct GitkrGtkWidget {
>>  GitkWidgetFields;
>>  GtkWidget *impl; /**< @brief the widget implementation */
>>};
>>
>>=== Doxyfile
>>
>>ENABLE_PREPROCESSING   = YES
>>MACRO_EXPANSION        = YES
>>EXPAND_ONLY_PREDEF     = NO
>>SEARCH_INCLUDES        = YES
>>SKIP_FUNCTION_MACROS   = YES
>>
>>===
>>
>>=== Problem 1:
>>when running doxygen it expands the macro there, but complains about
>>undocumented variables. Are the documentes inside the define dropped?
>>
>>header1.h:6:Warning: Member id of class GitkWidget is not documented.
>>header1.h:6:Warning: Member context of class GitkWidget is not documented.
>>header1.h:6:Warning: Member type of class GitkWidget is not documented.
>>
>>=== Problem 2:
>>it does not expand the define in the second header file. Both, the data-fields
>>list and the graph are missing the 'inherited' elements.
>>
>>header2.h:3:Warning: Member GitkWidgetFields of class GitkrGtkWidget is not
>>documented.
>>
>>===
>>
>>Anyway, does anyone has a better idea, of how to do 'inheritance' in C (not
>>C++). Unfortunately I am bound to use gcc 2.95 and this one does not support
>>anonymous structs/unions.
>>Wouldn't it be a good idea to have a @extends command (which should not be used
>>in C++/Java) so that I call documents such relations even in C.
>>
>>Ciao
>>  Stefan
>>-- 
>>      \|/            Stefan Kost
>>     <@ @>           private            business
>>+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
>>|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
>>|      ///           04277 Leipzig      04251 Leipzig
>>| __  ///            Germany            Germany
>>| \\\///    Phone    +49341 2253538     +49341 30766101
>>|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
>>|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
>>===-=-=--=---=---------------------------------- - - -  -    -
>>
>>
>>
>>-------------------------------------------------------
>>This SF.net email is sponsored by: IBM Linux Tutorials.
>>Become an expert in LINUX or just sharpen your skills.  Sign up for IBM's
>>Free Linux Tutorials.  Learn everything from the bash shell to sys admin.
>>Click now! http://ads.osdn.com/?ad_id=1278&alloc_id=3371&op=click
>>_______________________________________________
>>Doxygen-develop mailing list
>>Dox...@li...
>>https://lists.sourceforge.net/lists/listinfo/doxygen-develop
> 
> 

-- 
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
|      ///           04277 Leipzig      04251 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -

Re: [Doxygen-develop] doxygen preprocessor, not always expands

[Stefan K. <ko...@im...>]

Hi Sigmund,

many thanks, that works. I hope that Dimitri will apply the patch.

Ciao
 Stefan

Sigmund Augdal wrote:
>>was the patch denied or ignored. Maybe should should you should bug dimitri to
>>pay attantion to it again. Unfortunately I get thousands of diffenrences when
>>comparing doxygen 1.3.5 (to which I just have upgraded). So I am not sure, what
>>and how much you actually have changed.
> 
> The patch was ignored if I recall correct. The version I linked to was a
> patched version about 1.3.1, so there should be many changes compared to
> 1.3.5. Therefor I resend the patch adapted to 1.3.5. Hope it suits your
> needs, and hope it will be accepted in some form.
> 
> Sigmund

-- 
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
|      ///           04277 Leipzig      04251 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -

Re: [Doxygen-develop] doxygen preprocessor, not always expands

[Dimitri v. H. <di...@st...>]

On Tue, Dec 09, 2003 at 03:49:26PM +0100, Stefan Kost wrote:
> Hi Sigmund,
> 
> many thanks, that works. I hope that Dimitri will apply the patch.

I don't think the patch was a complete fix of the problem (that's 
why I didn't integrate it). I'm now working on a complete solution, which 
requires teaching the preprocessor routines to cope with comment blocks.

Regards,
  Dimitri

Re: [Doxygen-develop] doxygen preprocessor, not always expands

[Stefan K. <ko...@im...>]

hi dimitri,

Okay and thanks a lot.

> On Tue, Dec 09, 2003 at 03:49:26PM +0100, Stefan Kost wrote:
> 
>>Hi Sigmund,
>>
>>many thanks, that works. I hope that Dimitri will apply the patch.
> 
> 
> I don't think the patch was a complete fix of the problem (that's 
> why I didn't integrate it). I'm now working on a complete solution, which 
> requires teaching the preprocessor routines to cope with comment blocks.
> 
> Regards,
>   Dimitri
> 
> 
> 
> -------------------------------------------------------
> This SF.net email is sponsored by: IBM Linux Tutorials.
> Become an expert in LINUX or just sharpen your skills.  Sign up for IBM's
> Free Linux Tutorials.  Learn everything from the bash shell to sys admin.
> Click now! http://ads.osdn.com/?ad_id=1278&alloc_id=3371&op=click
> _______________________________________________
> Doxygen-develop mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-develop
> 

-- 
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
|      ///           04277 Leipzig      04251 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -

Re: [Doxygen-develop] doxygen preprocessor, not always expands

[Stefan K. <ko...@im...>]

Hi again,


> === Problem 1:
> when running doxygen it expands the macro there, but complains about
> undocumented variables. Are the documentes inside the define dropped?
> 
> header1.h:6:Warning: Member id of class GitkWidget is not documented.
> header1.h:6:Warning: Member context of class GitkWidget is not documented.
> header1.h:6:Warning: Member type of class GitkWidget is not documented.
> 
I've found it to be number 49 on Doxygens todo/wishlist.
seems to happens somewhere in 'src/pre.cpp' although after a first look at the
source I don't dare to change anything there.
Dimitri: any chance that you can resolve this for the next version?

> === Problem 2:
> it does not expand the define in the second header file. Both, the data-fields
> list and the graph are missing the 'inherited' elements.
> 
> header2.h:3:Warning: Member GitkWidgetFields of class GitkrGtkWidget is not
> documented.
> 
> ===
> 
> Anyway, does anyone has a better idea, of how to do 'inheritance' in C (not
> C++). Unfortunately I am bound to use gcc 2.95 and this one does not support
> anonymous structs/unions.
> Wouldn't it be a good idea to have a @extends command (which should not be used
> in C++/Java) so that I call documents such relations even in C.
> 
> Ciao
>   Stefan

-- 
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
|      ///           04277 Leipzig      04251 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -

Re: [Doxygen-develop] doxygen preprocessor, not always expands

[Stefan K. <ko...@im...>]

Hi Dimitri,

I've had a deeper look into it.

> === Problem 1:
> when running doxygen it expands the macro there, but complains about
> undocumented variables. Are the documentes inside the define dropped?
> 
> header1.h:6:Warning: Member id of class GitkWidget is not documented.
> header1.h:6:Warning: Member context of class GitkWidget is not documented.
> header1.h:6:Warning: Member type of class GitkWidget is not documented.
> 
As I've already found out it wish-item 49:
And it look to me that in 'src/pre.l' the following line need to be changed :
<SkipLine,SkipCommand,SkipCPPBlock>"//"	{
  					  g_lastCPPContext=YY_START;
  					  BEGIN(RemoveCPPComment);
					}
<SkipLine,SkipCommand,SkipCPPBlock>"/*"	{
					  g_lastCContext=YY_START;
  					  BEGIN(RemoveCComment);
  					}

so that doxygen-comments (/**) are not removed, e.g like below (this might not
work as I just have started to read about lex and co - I've never used them before).

<SkipLine,SkipCommand,SkipCPPBlock>"/*"{
					  g_lastCContext=YY_START;
  					  BEGIN(CComment);
  					}
<CComment>"*"				{
					  BEGIN{CopyCComment};
					}
<CComment>[^*]				{
  					  BEGIN(RemoveCComment);
					}

I would be really happy if this could be fixed soon, as I have a deadline at the
end of this year :-(.

Ciao
  Stefan

> === Problem 2:
> it does not expand the define in the second header file. Both, the data-fields
> list and the graph are missing the 'inherited' elements.
> 
> header2.h:3:Warning: Member GitkWidgetFields of class GitkrGtkWidget is not
> documented.
> 
> ===
> 
> Anyway, does anyone has a better idea, of how to do 'inheritance' in C (not
> C++). Unfortunately I am bound to use gcc 2.95 and this one does not support
> anonymous structs/unions.
> Wouldn't it be a good idea to have a @extends command (which should not be used
> in C++/Java) so that I call documents such relations even in C.
> 
> Ciao
>   Stefan

-- 
      \|/            Stefan Kost
     <@ @>           private            business
+-oOO-(_)-OOo------------------------------------------------------ - - -  -   -
|       __  Address  Simildenstr. 5     HTWK Leipzig, Fb IMN, Postfach 301166
|      ///           04277 Leipzig      04251 Leipzig
| __  ///            Germany            Germany
| \\\///    Phone    +49341 2253538     +49341 30766101
|  \__/     EMail    st_kost_at_gmx.net kost_at_imn.htwk-leipzig.de
|           WWW      www.sonicpulse.de  www.imn.htwk-leipzig.de/~kost/about.html
===-=-=--=---=---------------------------------- - - -  -    -