Add better documentation for service alerts

Summary:

We currently don't do a very good job of sharing information with agencies for how service alerts appear in Android or iOS, including configuration changes agencies can make to change the presentation of the alert.

On OBA Android, here's our mapping of colors of the alerts to the "Severity" level of alerts:

Looking at the code, we have three types internally in Android: • ERROR – red • WARNING – yellow • INFO – green

Here’s how that maps to service alerts impacts:

if (ObaSituation.SEVERITY_NO_IMPACT.equals(mSituation.getSeverity())) {
    return TYPE_INFO;
} else if (ObaSituation.SEVERITY_SEVERE.equals(mSituation.getSeverity())
        || ObaSituation.SEVERITY_VERY_SEVERE.equals(
        mSituation.getSeverity())) {
    return TYPE_ERROR;
} else {
    // Treat all other ObaSituation.SEVERITY_* types as a warning
    return TYPE_WARNING;
}

So if you label something “Severe” or “Very severe” it is red, “No impact” is green, and everything else is yellow.

We should create better documentation for this for agencies as well as developers - right now "situation" elements aren't documented in the REST API docs for the main arrivals-and-departures-for-stop API: http://developer.onebusaway.org/modules/onebusaway-application-modules/current/api/where/elements/arrival-and-departure.html

It looks like the situation element docs are someone hidden – there isn’t a link to them anywhere, but if you follow the same URL pattern you get http://developer.onebusaway.org/modules/onebusaway-application-modules/current/api/where/elements/situation.html. I’ve never reviewed these, so I don’t know if they reflect the current state of the API.

Here's an example REST API request - as of June 2018 HART has a few active alerts, which show up as situation elements in the references section: http://api.tampa.onebusaway.org/api/api/where/arrivals-and-departures-for-stop/Hillsborough%20Area%20Regional%20Transit_6497.json?minutesAfter=65&app_ver=91&version=2&key=TEST

I’ve grabbed some past arrivals-and-departues-for-stop API responses that I’ve used in unit tests for Android – here are the files: • https://github.com/OneBusAway/onebusaway-android/blob/master/onebusaway-android/src/androidTest/res/raw/arrivals_and_departures_for_stop_dart_4041_alerts.json • https://github.com/OneBusAway/onebusaway-android/blob/master/onebusaway-android/src/androidTest/res/raw/arrivals_and_departures_for_stop_psta_4077_alerts.json • https://github.com/OneBusAway/onebusaway-android/blob/master/onebusaway-android/src/androidTest/res/raw/arrivals_and_departures_for_stop_mts_11670_route_alerts.json • https://github.com/OneBusAway/onebusaway-android/blob/master/onebusaway-android/src/androidTest/res/raw/arrivals_and_departures_for_stop_mts_13353_route_and_stop_alerts.jso

The unit tests that use these files are here – just search for the word “situation” in the method names: https://github.com/OneBusAway/onebusaway-android/blob/master/onebusaway-android/src/androidTest/java/org/onebusaway/android/io/test/ArrivalInfoRequestTest.java

We should also try to normalize colors and other presentation with OBA iOS.

OneBusAway / onebusaway-android

Add better documentation for service alerts #714