Re: [avr-libc-dev] Documentation/Lib mismatch for inverse( ) function in math lib?

[Joerg Wunsch]

As Wouter van Gulik wrote:

> I think there is a documentation flaw for the math lib.  The
> documentation states there is function: double inverse(double ).

Hmm, I was not aware that this function was actually exported and
documented to be exported.  I recently renamed all supposedly internal
(to libm/FPlib) function entries to __fp_XXX names so they do not risk
a collision with the application's name space.  inverse() has thus
been renamed to __fp_inverse().

Well, if people think it has substantial value to be made publically
available, I could undo that particular change.

> I also noticed that the documentation is not consequent on the
> inverse function: all math functions are documented with __x as
> argument. But not for the inverse function . So it seems like a
> documentation bug to me.

The __ prepended to all function args is a rather unfortunate
side-effect of the way the documentation is generated.  As most of the
documentation is extracted by doxygen out of header files, we wanted
to avoid a collision with the application's name space (again).
Suppose the user has a macro like

#define x somestruct->val->x

in effect before he includes a system header such as <math.h>.  Now
imagine a function declaration like

double inverse(double x);

there, preprocessing would yield

double inverse(double somestruct->val->x);

which is most likely not valid C code. ;-)  To avoid that, all
declarations are supposed to look like

double inverse(double __x);

as the leading underscores reserve it for `the implementation'.

So yes, this is a bug.  However, its resolution depends on whether we
are going to withdraw the function inverse() from public namespace
alltoghether or not.

-- 
cheers, J"org               .-.-.   --... ...--   -.. .  DL8DTL

http://www.sax.de/~joerg/                        NIC: JW11-RIPE
Never trust an operating system you don't have sources for. ;-)