Re: stack module

[Bruno Haible]

Hi Paul,

> Something like the attached?

This documentation is quite misleading:

  +/* Check E's value at runtime, and report an error and abort if not.
  +   However, do nothing if NDEBUG is defined; in this case behavior is

because the "do nothing" is an understatement. 'assume' is a dangerous macro,
because it allows the compiler to do optimizations based on putative
assumptions. Since 'affirm' invokes 'assume', the documentation should
emphasize this danger.

How about this instead?

/* States an assertion that the programmer believes to be true.
   When NDEBUG is not defined, this macro is like assert: it verifies the
   assertion at run time and aborts the program if the assertion is not true.
   When NDEBUG is defined, the programmer guarantees that the assertion is
   true, and the macro informs the compiler about it, so that the compiler
   may produce optimized code based on it.  */

Bruno