Add better documentation for route service alerts in arrivals-and-departures-for-stop

[barbeau]

In arrivals-and-departures-for-stop API (http://app.staging.obahart.org/api/api/where/arrivals-and-departures-for-stop/Hillsborough%20Area%20Regional%20Transit_6497.json?key=TEST), if you add a situation (service alert) specific to a stop, in the response you see a situationId for that alert appear within the entry element, like this:

{
currentTime: 1474555216964,
text: "OK",
data: {
...
entry: {
situationIds: [
"Hillsborough Area Regional Transit_74450e82-bb69-4db8-855a-ee69e012305f"  // <-- service alert specific to this stop
],
stopId: "Hillsborough Area Regional Transit_6497",
arrivalsAndDepartures: [
{
...

However, if you set a situation specific to a route, the situationIds element is empty:

{
currentTime: 1474555557601,
text: "OK",
data: {
...
entry: {
situationIds: [ ],  // <-- Should this contain the route-specific situations for arrivals at this stop?
stopId: "Hillsborough Area Regional Transit_6497",

In both cases, the situations are still included in the references element.

@sheldonabrown Do you know if this intended behavior or a bug?

The arrivals-and-departures-for-stop API documentation doesn't even contain the situationIds element, as I think it was added late in the life of OBA at UW, so it's not much of a help: http://developer.onebusaway.org/modules/onebusaway-application-modules/current/api/where/elements/arrival-and-departure.html

This was reported by San Diego MTS on the mailling list - https://groups.google.com/forum/#!topic/onebusaway-developers/dCK0HSaEh1c. Apparently OBA Android is looking at this element for alerts, and if it's empty no alerts are shown. Apparently other clients (iOS, web) are looking at the references elements for alerts, and show alerts:

[sheldonabrown]

Looking at the code, it looks like (for performance reasons?) we only look for service alerts related to that stop, we don't consider querying for the route:

https://github.com/camsys/onebusaway-application-modules/blob/unified/onebusaway-transit-data-federation/src/main/java/org/onebusaway/transit_data_federation/impl/beans/StopWithArrivalsAndDeparturesBeanServiceImpl.java#L80

This could go either way, bug or design choice, but clearly the documentation should reflect that.

[barbeau]

The more I look at this, the more I think it's a design choice. Agency and stop-specific alerts are relevant to the entire stop (and therefore in the main situationIds element), while route-specific alerts are only relevant to specific routes (and not the entire stop). So I'd vote for leaving the implementation as-is, and add these details to the documentation. I'm fixing OBA Android so it displays route-specific alerts along with stop and agency-specific alerts - https://github.com/OneBusAway/onebusaway-android/pull/701.

I'll leave this issue open until we update the docs.

[barbeau]

New documentation for this should probably appear in both the Situation and arrivals-and-departures-for-stop sections (and maybe others?.

Some proposed text (feel free to improve):

Agency and stop-specific alerts are relevant to the entire stop (and therefore in the main situationIds element as well as the references element), while route-specific alerts are only relevant to specific routes (and not the entire stop) and therefore do not appear in the situationIds element but do appear in the references element.