From 2b997d89906598b0de774cadb40ca42ec66c87d4 Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@finalrewind.org>
Date: Sun, 21 Jun 2015 21:45:46 +0200
Subject: document route functions

---
 lib/Travel/Status/DE/EFA.pm        | 10 +++++++
 lib/Travel/Status/DE/EFA/Result.pm | 59 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)

diff --git a/lib/Travel/Status/DE/EFA.pm b/lib/Travel/Status/DE/EFA.pm
index 00338b7..f261855 100644
--- a/lib/Travel/Status/DE/EFA.pm
+++ b/lib/Travel/Status/DE/EFA.pm
@@ -328,6 +328,10 @@ sub parse_route {
 		my @dates = $e->findnodes($xp_routepoint_date);
 		my @times = $e->findnodes($xp_routepoint_time);
 
+		# note that the first stop has an arrival node with an invalid
+		# timestamp and the terminal stop has a departure node with an
+		# invalid timestamp.  sprintf_{date,time} return undef in these
+		# cases.
 		push(
 			@ret,
 			{
@@ -555,6 +559,12 @@ B<stop> (stop/station name).
 
 address / poi / stop name to list departures for.
 
+=item B<full_routes> => B<0>|B<1>
+
+If true: Request full routes for all departures from the backend. This
+enables the B<route_pre>, B<route_post> and B<route_interesting> accessors in
+Travel::Status::DE::EFA::Result(3pm).
+
 =item B<timeout> => I<seconds>
 
 Request timeout, the argument is passed on to LWP::UserAgent(3pm).
diff --git a/lib/Travel/Status/DE/EFA/Result.pm b/lib/Travel/Status/DE/EFA/Result.pm
index ff581f0..674f1ba 100644
--- a/lib/Travel/Status/DE/EFA/Result.pm
+++ b/lib/Travel/Status/DE/EFA/Result.pm
@@ -197,6 +197,22 @@ otherwise.
 Unfortunately, there is no distinction between tram and bus platforms yet,
 which also may have the same numbers.
 
+=item $departure->route_interesting
+
+List of up to three "interesting" stations served by this departure. Is a
+subset of B<route_post>. Each station is a hash reference, see ROUTE STATIONS
+for details.
+
+=item $departure->route_pre
+
+List of stations the train passed (or will have passed) befoe this stop.
+Each station is a hash reference, see ROUTE STATIONS for details.
+
+=item $departure->route_post
+
+List of stations the train will pass after this stop.
+Each station is a hash reference, see ROUTE STATIONS for details.
+
 =item $departure->sched_date
 
 Scheduled departure date (DD.MM.YYYY).
@@ -261,6 +277,49 @@ The following are known so far:
 
 =back
 
+=head1 ROUTE STATIONS
+
+The B<route> accessors return hashrefs, each of which corresponds to a single
+station. Note that the route is solely based on the schedule, delays or
+changed platforms are not taken into account.
+
+For a station I<$stop>,
+the following keys are available:
+
+=over
+
+=item $stop->{arr_date}
+
+arrival date (DD.MM.YYYY). undef if this is the first scheduled stop.
+
+=item $stop->{arr_time}
+
+arrival time (HH:MM). undef if this is the first scheduled stop.
+
+=item $stop->{dep_date}
+
+departure date (DD.MM.YYYY). undef if this is the final scehduled stop.
+
+=item $stop->{dep_time}
+
+departure time (HH:MM). undef if this is the final scehduled stop.
+
+=item $stop->{stop}
+
+stop name with city prefix ("I<City> I<Stop>", for instance
+"Essen RE<uuml>ttenscheider Stern").
+
+=item $stop->{stop_suf}
+
+stop name without city prefix, for instance "RE<uuml>ttenscheider Stern".
+
+=item $stop->{platform}
+
+Platform name/number if available, empty string otherwise.
+
+=back
+
+
 =head1 DIAGNOSTICS
 
 None.
-- 
cgit v1.2.3