Since Apple doesn't make it easy to deploy DocC docs, try using a Github Action & Github Pages to deploy docs using this package

https://github.com/DoccZz/docc2html

Currently, using GTFS feeds in the package is awful. There's no real way to get the data from the feeds. WMATA is focusing heavily on GTFS feeds. For example coming January 28th, 2022:

As of January 28, 2022, WMATA is proud to announce some major enhancements to the station data with the launch of platforms, levels, pathways, and more precise stop locations in GTFS feed. These features will deliver more accurate travel times for trips, easier wayfinding, and real-time accessible trip planning.

Developers can use this new information for a variety of improvements , such as:

· Improving wayfinding for trip plans by showing names and locations of station entrances, as well as platform information

· Displaying more details on maps, like separate entrance locations (and their accessibility) and platforms

· Providing more accurate station guides for users

· Delivering more accurate travel times for trips by incorporating pathways information and varying the time for accessible trips

Due to these enhancements, Stops Times and Trips in the GTFS feed will refer to new stops (platforms). Consequently, GTFS Static and GTFS RT will use these new stop ids. An example of the new GTFS feed can be found here.

Source https://developer.wmata.com

Allow parsing of GTFS APIs into structures a la standard API.

The WMATA result for https://api.wmata.com/Bus.svc/json/jStops?Lat=38.898303&Lon=-77.028099&Radius=100 returns

{
  "Stops": [{
    "StopID": "1001051",
    "Name": "F ST NW + 12TH ST NW",
    "Lon": -77.027878,
    "Lat": 38.897441,
    "Routes": ["54", "54*1"]
  }]
}

but this result leads to an error "The operation couldn’t be completed. (WMATA.WMATAError error 1.)" using this package.

Since v11 of WMATA.swift, Route has been a typealias for String. Prior to v11, Route was a struct, and before that Route was an enum similar to Station, and way, way back Route was actually a class.

There's been a lot of shifting to figure out what the right type for this rather simple piece of data is. I think today's String value is the closest to correct so far, but it still isn't quite satisfactory. Some sharp edges remain with Routes that I think can be alleviated.

A Route has two fundamental parts: The actual route and the variant. Examples:

Route values: A4, Z8 W2

Variants values: /*2, *4, /

Both values can change often as new routes and variants are introduced. Currently, the String value of Route handles these frequent changes. However, several of WMATA's APIs like Bus.Positions and Bus.Incidents do not allow for variants when calling them. This is documented, but it's still possible to call the APIs using routes with variants since Route is just a String.

Here, the package can improve developer experience. If Route was its own type with knowledge of the route value and the variant provided by the developer, the package could choose to use the correct Route information in each endpoint. This would move guidance from documentation into typed checks in code, which is almost always preferable.

Here's the type I think could work well for Route:

struct Route: Codable, RawRepresentable {
    var route: String
    var variant: String?

    init(_ route: String, variant: String? = nil) {
       ...
    }
    
    init?(rawValue: String) {
        ...
    }
}

Route(rawValue: "Z8*4")
Route("10A")
Route("Z8", variant: "*4")

I think it could be a pain to parse the routes coming out go WMATA's API into their two parts because the WMATA is super inconsistent about naming route variants.

Overall though, I think this struct would allow the package to help the developer more and more accurately represent what a Route actually is.

Any input welcome.

When encoding a Route instance with JSONEncoder, previously a Route would be encoded as

"route": "10A"

under v9, Routes are encoded as

"route": { "id": "10A" }

which breaks Decoding & is a breaking change

Currently I think the usage of let is a bit onerous in the data coming back from the API. I think it's fine if they're moved to vars, and could make some development a bit easier.

There currently isn't a great mechanism to modify the data you receive from the API without creating a brand new struct, which can be tedious. If your project uses the data structures provided by this package, and it needs to modify the data it gets in some way, I think it should be able to do that.

Currently, it's not obvious how to determine if a metro customer can actually ride on a train returned from the NextTrains endpoint. WMATA recommends checking destinationName for the value "No Passenger".

Goal: Build a computed property that does this check for users.