Fix waypoints APIs naming for map matching and directions services

[Guardiola31337]

Follow up PR from latest feedback in #961

Edited:

• Fix waypoints APIs naming for map matching and directions services - from waypoints to separatesLegs waypoint indices 👀 Fix waypoints APIs naming for map matching and directions services #962 (comment)

Noting that for the Map Matching service we're deprecating

mapbox-java/services-matching/src/main/java/com/mapbox/api/matching/v5/MapboxMapMatching.java

Line 488 in c834c07

public Builder waypoints(@Nullable @IntRange(from = 0) Integer... waypoints) {

in favor of

mapbox-java/services-matching/src/main/java/com/mapbox/api/matching/v5/MapboxMapMatching.java

Line 507 in aba088c

public Builder waypointIndices(@Nullable @IntRange(from = 0) Integer... waypointIndices) {

to avoid breaking SemVer.

cc @1ec5

[danesfeder]

@Guardiola31337 left some comments regarding naming / javadoc. We are close, but imo this is still a little confusing for developers looking at the documentation for the first time. cc @1ec5

[danesfeder]

Does traces make sense here? Reading this javadoc, I'm still not entirely sure what separateLegs means.

set which input coordinates should be treated as separate legs.

By adding coordinates to a Directions API request, you are creating new legs. I think it may make sense here to say that separateLegs is directly influencing the guidance behavior when set.

[Guardiola31337]

#962 (comment)

[Guardiola31337]

After some discussion, we agreed on fixing the naming to "waypoint indices":

• In the Map Matching service the indices added mean which coordinates should act as "actual waypoints".
  Edited:
• In the Directions service the indices added mean which waypoints should be "silent" (from a guidance point of view). Note the explicit silent naming used here coordinates should act as "actual waypoints". 👀 Fix waypoints APIs naming for map matching and directions services #962 (comment)

Hope this is clear now.

cc @osana @1ec5 @mcwhittemore

[Guardiola31337]

• In the Directions service the indices added mean which waypoints should be "silent" (from a guidance point of view). Note the explicit silent naming used here.

Actually, this is not technically correct because coordinate indices not added act as silent waypoints, so not adding them is what makes them silent.

I'm updating (last time, promise!) the naming to waypointIndices and adding a note to Javadoc so it makes total sense to developers using the services. FWIW both Map Matching and Directions services will use the same nomenclature which was the initial goal of this PR.

Sorry for the back and forth.

[danesfeder]

Thanks for the updates @Guardiola31337 this is much more clear

[langsmith]

@danesfeder & @Guardiola31337 , if needed, please don't forget about updating mentions of waypoints in https://docs.mapbox.com/android/java/overview/directions/ and/or https://docs.mapbox.com/android/java/overview/map-matching/

thanks

cc @colleenmcginnis