RFC: Avoiding #warning (C/C++ preprocessor extension)

[Adriaan de Groot]

On Monday 31 October 2005 21:26, Nicolas Goutte wrote:
> On Monday 31 October 2005 00:13, Jaroslaw Staniek wrote:
> > Olivier Goffart said the following, On 2005-10-31 00:16:
> > > All of this is correct.
> > > Anyway, #warning are just temporary code,  and they should be removed
> > > before the release.
> > > A good code compiles without warnings at all.
> > >
> > > We should not simply remove the #warning line,  but also fix the code.
> >
> > Yes, so I asked about a way to replace #warning with something similar
> > but allowing the code to compile.

The issue is that @todo's are much easier to ignore than #warnings. You don't 
see the @todo _at all_ unless you either (a) grep for them (b) look on EBN 
(c) generate apidox yourself.

> > > This is a bit different: @todo are placed in header, and not directly
> > > in the code they show.
> >
> > Could there be a problem with placing them directly in the code? We're
> > already using doxygen in the code, in particular, @internal
>
> If it has not changed in the meantime, only headers are parsed for the
> on-line Doxygen documentation.
>
> If it is not there as @todo, it is not much of an alternative.

Doxygen processes *.h, *.cc, *.cpp and more; this is not an issue (for 
instance, for internal dox you can put them in the .cpp file). Running the 
following (stick it in a C++ file) through Doxygen does generate a sensible 
todo entry:

/** Bar class. */
class bar {
public:
/** Do foo() */
int foo()
{
        int i;
        /** @todo Defrobnicate */
        int j;
        bar(&j);
        return j;
}

} ;


> > > also #warning are generally used for more important things, while @todo
> > > may be long terms.
> > > There is also a flag to make all warnings act like fatal error, to
> > > force to fix them.
> >
> > So what about @warning ?

That's just moving the problem around. Instead of developers not looking at 
the @todo page, we'll have developers not looking at the @warning page. 
Remember, the trick is to irritate developers sufficiently to get them to fix 
things, but not to irritate them too much -- witness recent apidox blog 
festivities.

To put a positive twist on things: hypothetically the #warnings are put there 
by developers who want to remember to do something; they should be watching 
for developments in their code _anyway_, and the @todo list is a more general 
and more flexible way to do it. So they'll be looking at the @todo list 
_anyway_. (Note, though, that the @todo list is generated per Doxygen 
invocation, which is probably per-directory).


-- 
These are your friends - Adem
    GPG: FEA2 A3FE Adriaan de Groot