Re: [avr-libc-dev] [RFC] setjmp.h dox

[Theodore A. Roth]

On Wed, 4 Sep 2002, Joerg Wunsch wrote:

:) As Joerg Wunsch wrote:
:)
:) > >  extern int setjmp(jmp_buf __jmpb);
:) > >  extern void longjmp(jmp_buf __jmpb, int __ret) __ATTR_NORETURN__;
:) >
:) > One thing i also noticed when working over <stdlib.h> is that i think
:) > prepending two underscores to every formal parameter used in a
:) > declaration doesn't make any sense to me.

I'd have to agree.

:) > The scope of these names is
:) > just the declaration itself, so there's no risk of conflicting with
:) > any application-supplied names.
:)
:) I have to correct myself. ;-)  I can see why prepending the underscores
:) makes it safer: if the luser #defines a macro with the name of one of
:) those internal formal parameters before #including these headers, they
:) are likely to create syntax errors.

Fair enough. Looking through /usr/include/stdlib.h I see this:

  /* Convert a string to an integer.  */
  extern int atoi (__const char *__nptr) __THROW __attribute_pure__;

while the man page uses:

  int atoi(const char *nptr);

:)
:) > However, now that we use doxygen to
:) > document the header files, these names find their way into the user
:) > documentation.
:)
:) But then, this somewhat defeats the entire idea behind doxygen.  If we
:) have to escape all our formal parameters (that are not strictly
:) necessary in a declaration, but are required for documentation
:) purposes) with two underscores, it makes our documentation look
:) terrible. :(

Well, here one way to work around it (althought it's _very_ sub-optimal):

  #if defined(DOXYGEN)
  extern int setjmp(jmp_buf jmpb);
  #else
  extern int setjmp(jmp_buf __jmpb);
  #endif

or alternatively (even worse than above):

  #if define(DOXYGEN)
  #  define dox_arg(arg) arg
  #else
     /* does this even work like this? */
  #  define dox_arg(arg) __arg
  #endif

  extern int setjmp(jmp_buf dox_arg(jmpb));

I think both of the above are just plain bad ideas.

I do agree that the __ in the docs sucks. I tried using the \fn to declare
the function in the docs which only partially works as there were still
some __jmpb in the dox. Ick.

Ted Roth