ATAN2 results (are correct) vs documentation (is not correct)

I'm no expert on ATAN2, because it's a rather tricky trig function to understand. (Its wikipedia page is hundreds of lines long.) The KM function for ATAN2 returns value correctly for all four quadrants as per its mathematical requirements. But the KM documentation describes it incorrectly: "For arguments x,y, not both zero, this function returns the angle in radians between the x-axis and the point (x,y)." If this was true, then the result of ATAN2(1,-1) should return a value representing the fourth quadrant because the point 1,-1 is in the fourth quadrant. Instead, it gives a result in the second quadrant. Similarly the result of ATAN2(-1,1) is in the fourth quadrant rather than the second. There is nothing wrong with the KM ATAN2 function, it works as it should. The problem is the documentation isn't correct.

Indeed, what I need is a function that "returns the angle in radians between the x-axis and the point (x,y)". If such a function existed, I would use it a lot. As ATAN2 doesn't do that, I have to write lots of code to patch up how it actually works. It's messy.

In my opinion, this is a perfect example of why functions would be great for KM. As it stands now I have to write my messy patch code every time I try to use ATAN2.

The wiki description is correct (and indeed is the same as described on Wikipedia).

However note that the order of the arguments to the function ATAN2 is (y,x) not the usual (x,y). I have added clarity to the web page.

It does indeed give the result of the angle from the x axis to the point. ATAN2(1,-1) (y=1, x=-1 lies in the second quadrant and returns an angle of ~2.35 radians (135°).

Apparently I'm dyslexic. Thanks, sorry. It just proves you can't idiot-proof any documentation. Thanks.

I think I should mention that the other difference is that the Y coordinate's direction is reversed. In math, Y is up, while in screen coordinates, Y is down. This is what I was probably focussed on that made me lose sight of the parameter reversal. I'm always thinking "don't forget, Y is reversed" and that caused me to overlook that X and Y were also swapped.

Thanks, I added that to the wiki page as well.