What does "macro annotations embedding in comments" mean in mcpp?

Question

In mcpp.exe --help

Options available with only -@std (default) option:
-@compat    Expand recursive macro more than Standard.
-3          Enable trigraphs.
-K          **Output macro annotations embedding in comments.**

So, what does 'macro annotation in comments' mean?

http://mcpp.sourceforge.net/

Answer 1

From the mcpp-summary-272.pdf file available at SourceForge (link in question):

Also mcpp has a mode to output macro informations embedded in comments. This mode allows you to know macro calls and their locations on source file from preprocessed output.

So, it leaves behind comments identifying the macros expanded, so that you can tell which source came from which macro.

Illustration

Source (x.c)

#include <assert.h>
int main(int argc, char **argv)
{
    assert(argc != 0 && argv != 0);
    return 0;
}

mcpp x.c

#line 1 "/Users/jleffler/src/cmd/x.c"
#line 1 "/usr/include/assert.h"
#line 42 "/usr/include/assert.h"
#line 1 "/usr/include/sys/cdefs.h"
#line 417 "/usr/include/sys/cdefs.h"
#line 1 "/usr/include/sys/_symbol_aliasing.h"
#line 418 "/usr/include/sys/cdefs.h"
#line 494 "/usr/include/sys/cdefs.h"
#line 1 "/usr/include/sys/_posix_availability.h"
#line 495 "/usr/include/sys/cdefs.h"
#line 43 "/usr/include/assert.h"
#line 61 "/usr/include/assert.h"


void abort(void)  ;

int printf(const char *  , ...);

#line 2 "/Users/jleffler/src/cmd/x.c"
int main(int argc, char **argv)
{
    ((void) ((argc != 0 && argv != 0) ? 0 : ((void)printf ("%s:%u: failed assertion `%s'\n", "/Users/jleffler/src/cmd/x.c" , 4 , "argc != 0 && argv != 0"), abort()) )) ;
    return 0;
}

mccp -K x.c (excerpt)

I omitted about 560 lines of not very informative output, but the main code is:

#line 2 "/Users/jleffler/src/cmd/x.c"
int main(int argc, char **argv)
{
    /*<assert 4:5-4:35*//*!assert:0-0 4:12-4:34*/((void) ((/*<assert:0-0*/argc != 0 && argv != 0/*>*/) ? 0 : /*<__assert*//*!__assert:0-0*//*!__assert:0-1*//*!__assert:0-2*/((void)printf ("%s:%u: failed assertion `%s'\n", /*<__assert:0-1*//*<__FILE__*/"/Users/jleffler/src/cmd/x.c"/*>*//*>*/, /*<__assert:0-2*//*<__LINE__*/4/*>*//*>*/, /*<__assert:0-0*//*<assert:0-0*/"argc != 0 && argv != 0"/*>*//*>*/), abort())/*>*/))/*>*/;
    return 0;
}

Or, with comments isolated one per line (manually):

#line 2 "/Users/jleffler/src/cmd/x.c"
int main(int argc, char **argv)
{
    /*<assert 4:5-4:35*/
    /*!assert:0-0 4:12-4:34*/
    ((void) ((
      /*<assert:0-0*/
      argc != 0 && argv != 0
    /*>*/
             ) ? 0 :
    /*<__assert*/
    /*!__assert:0-0*/
    /*!__assert:0-1*/
    /*!__assert:0-2*/
    ((void)printf ("%s:%u: failed assertion `%s'\n",
    /*<__assert:0-1*/
    /*<__FILE__*/
    "/Users/jleffler/src/cmd/x.c"
    /*>*/
    /*>*/
    ,
    /*<__assert:0-2*/
    /*<__LINE__*/
    4
    /*>*/
    /*>*/
    ,
    /*<__assert:0-0*/
    /*<assert:0-0*/
    "argc != 0 && argv != 0"
    /*>*/
    /*>*/
    ), abort())
    /*>*/
    ))
    /*>*/
    ;
    return 0;
}

What is the bug in this implementation of the assert() macro?

Hint: the C99 standard says:

§7.2.1.1 The assert macro

The assert macro puts diagnostic tests into programs; it expands to a void expression. When it is executed, if expression (which shall have a scalar type) is false (that is, compares equal to 0), the assert macro writes information about the particular call that failed (including the text of the argument, the name of the source file, the source line number, and the name of the enclosing function — the latter are respectively the values of the preprocessing macros __FILE__ and __LINE__ and of the identifier __func__) on the standard error stream in an implementation-defined format. It then calls the abort function.

The machine is running MacOS X Lion (10.7.1).