LibRangeCheck-2.0

4 - Confusing API documentation(?)

What is the issue?
This could very well be a problem with my understanding seeing as I'm not a native speaker.

From the Docs.

Quote:

lib:GetFriendMinChecker(range)
Return a checker suitable for out-of-range checking on friendly units, that is, a checker whose range is equal or larger than the requested range.
Parameters
range
the range to check for.
Return value
checker, range pair or nil if no suitable checker is available. range is the actual range the returned checker checks for.

Please provide any additional information below.
The way I understand this (and the equivalent :GetHarmMinChecker(range)) from the colored part is that:
If I feed the library a valid range (eg. 20y) it will return me a function that I can call on a (friendly|hostile) unit.

I can then call checker("target") and if my target is 20 or more yards from me the checker will return true.
This perception at least is reinforced from the 'suitable for out-of-range checking on units' part.

That's not what happens.
checker(unit) returns true when I'm 'inside' the passed range (ie 'in range') and nil when I'm 'outside' ('out of range')
I can make this work in my addon obviously by inverting 'my logic' but I wanted to be sure this is not a bug to be fixed in the Lib which would have me make changes further down the road.

Thanks for reading :)

User When Change
mitch0 Mar 26, 2014 at 15:02 UTC Changed status from New to Fixed
Dridzt Jun 03, 2013 at 06:46 UTC Changed name from Misleading API documentation(?) to Confusing API documentation(?)
Dridzt Jun 02, 2013 at 22:54 UTC Create

You must login to post a comment. Don't have an account? Register to get one!

  • 3 comments
  • Avatar of Dridzt Dridzt Jun 03, 2013 at 08:36 UTC - 0 likes

    Thanks, your example makes it clear.

    I had already used it as you suggest but now I can also put my mind at ease that I understand the difference.

    I should have derived it from the source as you order checkers from long to short distance and your getMinChecker function is traversing the checkerList until it finds a shorter range then returns the one before it (ie the longer as you described).

    I'd already understood what the code does and used it accordingly, I just couldn't wrap my head around to 'why' it does it that way.

    The use-case you gave me helped clear it up :)

    Edit: Btw, on a slightly unrelated topic when I push a release (still need to test some things) how do I make it so my project is listed as a reverse-relationship and you get a point split?
    Project is hosted on curseforge side of things unfortunately.

    Last edited Jun 03, 2013 by Dridzt
  • Avatar of mitch0 mitch0 Jun 03, 2013 at 07:49 UTC - 0 likes

    (damn, my previous comment got lost upon submit...)

    All the checkers returned from LibRangeCheck work the same way: they return true if the target is WITHIN the specified range, so yes, if you want to check if the unit is out-of-range, you have to negate the result.

    The difference between GetFriendMinChecker and GetFriendMaxChecker are only visible if you request a checker for a range that we don't have an exact checker for.

    I think it's easier to understand by looking at an example:

    Let's say we have checkers for 5, 10, 15 and 20yd ranges, and we request checkers for 13yd range:

    GetFriendMinChecker(13) will return a checker that actually checks the 15yd range, so if this checker returns false, you can be sure that the unit is out-of-range regarding the 13yd limit. (that's what "suitable for out-of-range checking" means)

    on the other hand, GetFriendMaxChecker(13) will return a checker that checks the 10yd range, so if this checker returns true, you can be sure that the unit is in-range regarding the 13yd limit. (that's what "suitable for in-range checking" means)

    If you request a checker for a range that we have an exact-match for, both versions would return the same checker function (but you'd still have to negate the result for out-of-range checking), so: GetFriendMinChecker(15) and GetFriendMaxChecker(15) both return a checker that checks the 15yd range, and a true return value means that the unit is within the 15yd range.

    Hope this clears things up a bit... You can reach me on #wowace on irc.freenode.net if you need more online help ;)

    cheers, mitch

  • Avatar of Dridzt Dridzt Jun 02, 2013 at 23:11 UTC - 0 likes

    Furthermore from my testing loading the library in game :GetFriendMaxChecker(range) behaves the exact same way as MinChecker although the documentation and behavior in this instance seem to align.

    checker(unit) when checker is returned from :Get*MaxChecker(range) returns true when in-range and nil when out-of-range, so 'suitable for in-range checking' where 'range is equal or smaller'

  • 3 comments

Facts

Last updated
Mar 26, 2014
Reported
Jun 02, 2013
Status
Fixed - Developer made requested changes. QA should verify.
Type
Other - Some other kind of issue
Priority
Medium - Normal priority.
Votes
0

Reported by

Possible assignees