doxygen-users

[Doxygen-users] Behaviors of `gcc -E -C'

[Roberto B. <ba...@cs...>]

Hi there,

here is a problem I have encountered that may be of interest to both
the GCC and the DOXYGEN communities.
Consider the following 4 non-empty lines of C text:

#if 0
/* I would like not to see this. */
int x;
#endif

Put these 4 lines into a file called foo.c and then
try

    gcc -E -P -C foo.c

Here is the behavior I observe with different (official and unofficial)
versions of gcc:

egcs-2.91.66 (kgcc)  produces a blank line
egcs-2.95.3          produces a blank line
gcc 2.96-85 (RedHat) produces the comment I would like not to see
gcc 3.0.1            produces the comment I would like not to see
gcc 3.1 20011006     prints nothing (GOOD!)

This issue is quite relevant if one uses doxygen
(http://www.doxygen.org/), since there comments are relevant (whence
the use of `-C').  A situation where the behavior of gcc 2.96-85 and
gcc 3.0.1 may byte you is the following:

#if 0
/*! A comment referring to x. */
int x;
#endif
int y;

Doxygen uses special comments like the above (notice the exclamation
mark) for documentation.  When using doxygen is fed with text coming
from the GCC preprocessor, gcc 2.96-85 (RedHat) and gcc 3.0.1
cause a comment for (disregarded) x to be applied to y.
There are other tools that look inside comments to derive useful
information: these are also affected as well.

I wrote this message because I believe it is important not to
overlook the issue.  I have quickly checked the standard documents,
but I have not found anything that prescribes the behavior
that I consider "desirable".  I have also checked the documentation
of the `-C' option but this is also somewhat ambiguous on the subject.

A last question: even though the CVS HEAD version is OK
(for my purposes, at least), what will gcc 3.0.2 do?
All the best,

    Roberto

-- 
Roberto Bagnara
Computer Science Group
Department of Mathematics, University of Parma, Italy
http://www.cs.unipr.it/~bagnara/
mailto:ba...@cs...

[Doxygen-users] Re: Behaviors of `gcc -E -C'

[Neil B. <ne...@da...>]

There are various issues with -C which are not good.  It saves
comments within a macro expansion, so that each invocation reproduces
the comment.

This is nice, except that it doesn't work with C++ comments, since
stuff later on the line can be commented out (doh!) and it doesn't
work in directives, which don't expect comments as tokens.

These are fixable, if someone persuades me it's worth retaining the
comments in macro expansions.  We could convert C++ comments to C
comments when saving them, and have directives call a new function
_cpp_get_dtoken that filters out comment tokens.

What do you think, Zack?

In the meantime, I'm going to bootstrap the patch below, which turns
off saving comments in macro expansions, and if all is OK commit it.

As for 3.0.2, this patch plus a one-liner to fix the bug you mentioned
about comments in skipped blocks being output could be applied.  I'll
see what Mark thinks RSN.

Neil.

	* cppmacro.c (_cpp_create_definition): Leave comments off.

Index: cppmacro.c
===================================================================
RCS file: /cvs/gcc/gcc/gcc/cppmacro.c,v
retrieving revision 1.79
diff -u -p -r1.79 cppmacro.c
--- cppmacro.c	2001/10/08 06:15:13	1.79
+++ cppmacro.c	2001/10/08 18:02:46
@@ -1329,7 +1329,6 @@ _cpp_create_definition (pfile, node)
   else if (ctoken->type != CPP_EOF && !(ctoken->flags & PREV_WHITE))
     cpp_pedwarn (pfile, "ISO C requires whitespace after the macro name");
 
-  pfile->state.save_comments = ! CPP_OPTION (pfile, discard_comments);
   saved_cur_token = pfile->cur_token;
 
   if (macro->fun_like)
Index: doc/cpp.texi
===================================================================
RCS file: /cvs/gcc/gcc/gcc/doc/cpp.texi,v
retrieving revision 1.14
diff -u -p -r1.14 cpp.texi
--- cpp.texi	2001/09/24 22:53:10	1.14
+++ cpp.texi	2001/10/08 18:03:06
@@ -4228,15 +4228,11 @@ linemarkers.  @xref{Preprocessor Output}
 @item -C
 Do not discard comments.  All comments are passed through to the output
 file, except for comments in processed directives, which are deleted
-along with the directive.  Comments appearing in the expansion list of a
-macro will be preserved, and appear in place wherever the macro is
-invoked.
+along with the directive.
 
-You should be prepared for side effects when using @option{-C}; it causes
-the preprocessor to treat comments as tokens in their own right.  For
-example, macro redefinitions that were trivial when comments were
-replaced by a single space might become significant when comments are
-retained.  Also, comments appearing at the start of what would be a
+You should be prepared for side effects when using @option{-C}; it
+causes the preprocessor to treat comments as tokens in their own right.
+For example, comments appearing at the start of what would be a
 directive line have the effect of turning that line into an ordinary
 source line, since the first token on the line is no longer a @samp{#}.
 

[Doxygen-users] Re: Behaviors of `gcc -E -C'

[Zack W. <za...@co...>]

On Mon, Oct 08, 2001 at 07:10:12PM +0100, Neil Booth wrote:
> There are various issues with -C which are not good.  It saves
> comments within a macro expansion, so that each invocation reproduces
> the comment.

I don't remember why we tried to do this in the first place.  Until
someone can remember why, turning them off again seems like a sensible
plan.

> These are fixable, if someone persuades me it's worth retaining the
> comments in macro expansions.  We could convert C++ comments to C
> comments when saving them, and have directives call a new function
> _cpp_get_dtoken that filters out comment tokens.

All very doable.

I'd kind of like to see directives call a different function from
cpp_get_token, but for a different reason: right now profiling the
preprocessor is hindered by the gargantuan recursive cycle between all
the directive handlers (and their children) and cpp_get_token.  If
there were an internal version that did do macro expansion but
didn't do directive processing, and they used it, the cycle would go
away.

zw

[Doxygen-users] Re: Behaviors of `gcc -E -C'

[Neil B. <ne...@da...>]

Zack Weinberg wrote:-

> I don't remember why we tried to do this in the first place.  Until
> someone can remember why, turning them off again seems like a sensible
> plan.

The NetBSD project added a -CC option to cccp, which would preserve
comments in macros so that they are output wherever the macro is used,
rather than not at all or only where the macro is defined (I can't
remember what cccp does).  Which seems like a not unreasonable
improvement, to me at least.  Mainline CPP drops comments in
directives completely, even with -C, including #define.

> All very doable.
> 
> I'd kind of like to see directives call a different function from
> cpp_get_token, but for a different reason: right now profiling the
> preprocessor is hindered by the gargantuan recursive cycle between all
> the directive handlers (and their children) and cpp_get_token.  If
> there were an internal version that did do macro expansion but
> didn't do directive processing, and they used it, the cycle would go
> away.

Hmmm.  Directive processing is presently handled at the lexer level
rather than at the get_token / macro expansion level, since the
indicator of a directive is a '#' at the beginning of a logical line.
In other words, it's natural that directive processing can't happen in
directives, because in a directive you're not at the start of the
line.

So I'm not sure there is an clean split like that.

Neil.

Re: [Doxygen-users] Re: Behaviors of `gcc -E -C'

[Patrick O. <Pat...@pa...>]

On Thu, Oct 11, 2001 at 08:27:25PM -0700, Zack Weinberg wrote:
> On Mon, Oct 08, 2001 at 07:10:12PM +0100, Neil Booth wrote:
> > There are various issues with -C which are not good.  It saves
> > comments within a macro expansion, so that each invocation reproduces
> > the comment.
> 
> I don't remember why we tried to do this in the first place.  Until
> someone can remember why, turning them off again seems like a sensible
> plan.

I really like the idea of seeing the comments inside a macro after
expansion, because we are forced to use C and substitute templates
with some heavy use of the preprocessor. Debugging this is a nightmare,
and comments in the expanded code would help a lot.

I have tried it a while ago with egcs 2.91.66, which didn't work all
that well, but it seems that I should give it a second go with a more recent
version. Please, if you can keep this feature alive, then try it -
it is appreciated ;-)

-- 
Freundliche Gruesse / Best Regards

Patrick Ohly
Software Engineer
--------------------------------------------------------------------
//// pallas 
Pallas GmbH / Hermuelheimer Str. 10 / 50321 Bruehl / Germany
Pat...@pa... / www.pallas.com
Tel +49-2232-1896-30 / Fax +49-2232-1896-29
--------------------------------------------------------------------