Acknowledged
3 months ago
CIQQA-3063

bug: documentation typos in Toybox.Position.enableLocationEvents example

In https://developer.garmin.com/connect-iq/api-docs/Toybox/Position.html#enableLocationEvents-instance_function there are typos:

    if (Position has :CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1_L5) &&
       (Position.hasConfigurationSupport(Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1_L5)) {
        options[:configuration] = Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1_L5;
    } else if (Position has :CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1) &&
       (Position.hasConfigurationSupport(Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1)) {
        options[:configuration] = Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1;
    } else if (Position has :CONFIGURATION_GPS) &&
       (Position.hasConfigurationSupport(Position.CONFIGURATION_GPS)) {
        options[:configuration] = Position.CONFIGURATION_GPS;
    }

all 3 if have an "extra" zombie parentheses around the &&:

) &&

(

instead of just:

&&

update: and BTW the example code (with typecheck: 3, but I guess it doesn't matter in this case)  gives warnings:

options[:constellations] = [ Position.CONSTELLATION_GPS, Position.CONSTELLATION_GLONASS ];

enduro3: '$.Toybox.Position.CONSTELLATION_GPS' is deprecated.
enduro3: '$.Toybox.Position.CONSTELLATION_GLONASS' is deprecated.

flocsy🤠
Parents
  • 3 months ago

    As the example shows and the documentation (implicitly) explains, there are two sets of GPS enums:

    - API 3.3.6 and later: Position.Configuration (CONFIGURATION_*). Also, the Position module includes hasConfigurationSupport (which needs to be called to use the enums properly)

    - API 3.2.0 up to but not including API 3.3.6: Position.Constellation (CONSTELLATION_*). Also, the Position module does not include hasConfigurationSupport.

    The *full* example properly shows one way of accessing these enums correctly: by first checking for the existence of hasConfigurationSupport - if it exists, the newer CONFIGURATION enums are used, otherwise the older CONSTELLATION_* enums are used.

    Here's the relevant code (slightly more context that what was originally posted):

    //...
if (Position has :hasConfigurationSupport) {
    if (Position has :CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1_L5) &&
       (Position.hasConfigurationSupport(Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1_L5)) {
        options[:configuration] = Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1_L5;
    } else if (Position has :CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1) &&
       (Position.hasConfigurationSupport(Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1)) {
        options[:configuration] = Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1;
    } else if (Position has :CONFIGURATION_GPS) &&
       (Position.hasConfigurationSupport(Position.CONFIGURATION_GPS)) {
        options[:configuration] = Position.CONFIGURATION_GPS;
    }
} else if (Position has :CONSTELLATION_GLONASS) {
    // this can fail with InvalidValueException if combination is not supported by device
    options[:constellations] = [ Position.CONSTELLATION_GPS, Position.CONSTELLATION_GLONASS ];
} else {
    options = Position.LOCATION_CONTINUOUS;
}
//...

    To be clear: the deprecation warnings don't mean that the example is incorrect and they don't reflect an unknown problem in the compiler. It's the same old problem where a function/symbol is deprecated for one set of devices and not another, but the compiler isn't smart enough to only show the warning for the devices where it's actually deprecated.

    I would also argue that *specifically* for enduro3 (a CIQ 5.0.1 device), the warning is appropriate (yet still annoying) since those enums *are* deprecated for those devices. [That doesn't change the fact that the code as written is supposed to *also* support 3.2.0 devices though]

    If I built the (fixed) example for d2air (a CIQ 3.2.1), then the compiler would also show a deprecation warning for the CONSTELLATION enums, and in this case, I would consider than an unambiguous bug. (As the CONSTELLATION enums *are* not deprecated for that device)

    I'm gonna go ahead open another bug report for deprecation warning thing [although we've all complained about it before to no avail.]

    [2/2]

Comment
  • 3 months ago

    As the example shows and the documentation (implicitly) explains, there are two sets of GPS enums:

    - API 3.3.6 and later: Position.Configuration (CONFIGURATION_*). Also, the Position module includes hasConfigurationSupport (which needs to be called to use the enums properly)

    - API 3.2.0 up to but not including API 3.3.6: Position.Constellation (CONSTELLATION_*). Also, the Position module does not include hasConfigurationSupport.

    The *full* example properly shows one way of accessing these enums correctly: by first checking for the existence of hasConfigurationSupport - if it exists, the newer CONFIGURATION enums are used, otherwise the older CONSTELLATION_* enums are used.

    Here's the relevant code (slightly more context that what was originally posted):

    //...
if (Position has :hasConfigurationSupport) {
    if (Position has :CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1_L5) &&
       (Position.hasConfigurationSupport(Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1_L5)) {
        options[:configuration] = Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1_L5;
    } else if (Position has :CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1) &&
       (Position.hasConfigurationSupport(Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1)) {
        options[:configuration] = Position.CONFIGURATION_GPS_GLONASS_GALILEO_BEIDOU_L1;
    } else if (Position has :CONFIGURATION_GPS) &&
       (Position.hasConfigurationSupport(Position.CONFIGURATION_GPS)) {
        options[:configuration] = Position.CONFIGURATION_GPS;
    }
} else if (Position has :CONSTELLATION_GLONASS) {
    // this can fail with InvalidValueException if combination is not supported by device
    options[:constellations] = [ Position.CONSTELLATION_GPS, Position.CONSTELLATION_GLONASS ];
} else {
    options = Position.LOCATION_CONTINUOUS;
}
//...

    To be clear: the deprecation warnings don't mean that the example is incorrect and they don't reflect an unknown problem in the compiler. It's the same old problem where a function/symbol is deprecated for one set of devices and not another, but the compiler isn't smart enough to only show the warning for the devices where it's actually deprecated.

    I would also argue that *specifically* for enduro3 (a CIQ 5.0.1 device), the warning is appropriate (yet still annoying) since those enums *are* deprecated for those devices. [That doesn't change the fact that the code as written is supposed to *also* support 3.2.0 devices though]

    If I built the (fixed) example for d2air (a CIQ 3.2.1), then the compiler would also show a deprecation warning for the CONSTELLATION enums, and in this case, I would consider than an unambiguous bug. (As the CONSTELLATION enums *are* not deprecated for that device)

    I'm gonna go ahead open another bug report for deprecation warning thing [although we've all complained about it before to no avail.]

    [2/2]

Children
No Data