Improve Documentation

[phill44-source]

I find it unnecessarily complicated to need to look up the Classes in dvb/models.py so I would appreciate a UML Class Diagram. I myself could make one if necessary.

In addition, particular examples for the Attributes of the classes would be quite useful because I think their names are not specific enough.

[kiliankoe]

Hey @phill44-source, I added some doc comments to some types and attributes in models.py, I hope that helps a bit? If something is unclear, please say so and I'll improve it!

Regarding a diagram, feel free to create one and open a PR! :)

[phill44-source]

yes it does, thank you.
I've added a few changes to specific wordings can you look those over?
I have a few questions regarding the Data structure:

Why do the following have a unique ID?:

1. routeChange #One-time → Uniqueness unecessary
2. Pin # Already uniquely identifiable through coordinates, no?
3. Departure #Either a one-time thing(unique enough to make ID unecessary) or scheduled (Unique through the aspects scheduled, line, direction, (platform).

In addition, when looking at the diagram and attributes, a Regular stop does not inherit all attributes of a normal stop. Why is that?

The PartialRoute is a specific type of Line and as such to inherit all properties but "directions" might make sense. the Property "directions" could be deleted and there could be the property "direction" instead.

[kiliankoe]

All of these IDs are from the WebAPI, it's nothing the library sets. I don't have perfect information, but here's my best guesses:

1. Afaik these are not one-time events, a single route change can span validity periods, be referenced and updated over time.
2. Multiple pins can share the same location, you need the ID to differentiate.
3. The ID here is a trip ID that uniquely identifies the specific trip (a vehicle) and needed for the trip details endpoint.

Technically Stop and RegularStop are closely related, I agree. Inheritance is a bit of an issue with frozen dataclasses iirc (I don't do too much Python though tbh), but they also serve different purposes. Stop is just a search result, RegularStop is a stop within the context of a trip with timing and platform data.

Regarding the PartialRoute, it's also a bit more complicated. A Line is an entire transit line, e.g. a 7 running between Weixdorf and Pennrich. A PartialRoute is a single leg of a journey that uses a line, but also has other properties. The relationship is more "a PartialRoute uses a Line".

Do these things make sense?