📝🍎🚫💰 Update Swagger API documentation to explain non-revenue service …

…representation and prediction 'uncertainty' (#700)

* add uncertainty docs

* add revenue_status filter docs

* add revenue status description

* update wording

apps/api_web/lib/api_web/controllers/prediction_controller.ex

@@ -277,6 +277,61 @@ defmodule ApiWeb.PredictionController do
               "x-nullable": true
             )
 
+            arrival_uncertainty(
+              [:integer, :null],
+              """
+              Uncertainty value for the arrival time prediction.
+
+              Bus and Commuter Rail
+              See [entities tripUpdate stop_time_updates arrival uncertainty](https://swiftly-inc.stoplight.io/docs/realtime-standalone/613d1d7f1eae3-gtfs-rt-trip-updates)
+
+              | Value            | Description |
+              |------------------|-------------|
+              | < 300 or omitted |	Valid real-time prediction |
+              | 300              |  Real-time prediction not available. This code is primarily used when a vehicle has not yet been assigned to the trip, (i.e. because the block has not started yet). It is a schedule-based prediction, but Swiftly adjusts the schedule-based prediction time using observed historical travel times to make predictions more accurate than the schedule |
+              | 301              |	Valid real-time prediction, though the bus appears to be stalled or significantly delayed and predictions are not as accurate |
+              | > 301            |	Likely invalid prediction, recommend not showing anything (and not showing scheduled time), very rare situation |
+
+
+              Subway/Light Rail
+              See [GTFS `Realtime` `FeedMessage` `FeedEntity` `TripUpdate` `StopTimeUpdate` `arrival`](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-stoptimeupdate).
+
+              | Value  | Description |
+              |--------|-------------|
+              | 60   | A trip that has already started |
+              | 120  | A terminal/reverse trip departure for a trip that has NOT started and a train is awaiting departure at the origin |
+              | 360  | A terminal/reverse trip for a trip that has NOT started and a train is completing a previous trip |
+              """,
+              example: 60
+            )
+
+            departure_uncertainty(
+              [:integer, :null],
+              """
+              Uncertainty value for the departure time prediction.
+
+              Bus and Commuter Rail
+              See [entities tripUpdate stop_time_updates departure uncertainty](https://swiftly-inc.stoplight.io/docs/realtime-standalone/613d1d7f1eae3-gtfs-rt-trip-updates)
+
+              | Value            | Description |
+              |------------------|-------------|
+              | < 300 or omitted |	Valid real-time prediction |
+              | 300              | Real-time prediction not available. This code is primarily used when a vehicle has not yet been assigned to the trip, (i.e. because the block has not started yet). It is a schedule-based prediction, but Swiftly adjusts the schedule-based prediction time using observed historical travel times to make predictions more accurate than the schedule |
+              | 301              |	Valid real-time prediction, though the bus appears to be stalled or significantly delayed and predictions are not as accurate |
+              | > 301            |	Likely invalid prediction, recommend not showing anything (and not showing scheduled time), very rare situation |
+
+              Subway/Light Rail
+              See [GTFS `Realtime` `FeedMessage` `FeedEntity` `TripUpdate` `StopTimeUpdate` `departure`](https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-stoptimeupdate).
+
+              | Value | Description |
+              |-------|-------------|
+              | 60    | A trip that has already started |
+              | 120   | A terminal/reverse trip departure for a trip that has NOT started and a train is awaiting departure at the origin |
+              | 360   | A terminal/reverse trip for a trip that has NOT started and a train is completing a previous trip |
+              """,
+              example: 60
+            )
+
             schedule_relationship(
               :string,
               """