From 26deb42e6fca8206c437eb3223429ac0fec84fc2 Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@finalrewind.org>
Date: Mon, 23 May 2011 15:10:24 +0200
Subject: More descriptive accessor names in Net::Travel::DE::VRR::Route::Part

---
 lib/Net/Travel/DE/VRR/Route/Part.pm | 83 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 82 insertions(+), 1 deletion(-)

(limited to 'lib/Net/Travel/DE/VRR/Route/Part.pm')

diff --git a/lib/Net/Travel/DE/VRR/Route/Part.pm b/lib/Net/Travel/DE/VRR/Route/Part.pm
index d512fbb..a85e96c 100644
--- a/lib/Net/Travel/DE/VRR/Route/Part.pm
+++ b/lib/Net/Travel/DE/VRR/Route/Part.pm
@@ -9,7 +9,9 @@ use parent 'Class::Accessor';
 our $VERSION = '1.3';
 
 Net::Travel::DE::VRR::Route::Part->mk_ro_accessors(
-	qw(arr_stop arr_time dep_stop dep_time train_line train_dest));
+	qw(arrival_stop arrival_time departure_stop departure_time train_line
+	  train_destination)
+);
 
 sub new {
 	my ( $obj, %conf ) = @_;
@@ -36,30 +38,109 @@ points, without interchanges
 
 =head1 SYNOPSIS
 
+	for my $part ( $route->parts() ) {
+
+		if ( $part->extra() ) {
+			say join( "\n", $part->extra() );
+		}
+
+		printf(
+			"%s at %s -> %s at %s, via %s to %s",
+			$part->departure_time, $part->departure_stop,
+			$part->arrival_time,   $part->arrival_stop,
+			$part->train_line,     $part->train_destination,
+		);
+	}
+
 =head1 VERSION
 
 version 0.3
 
 =head1 DESCRIPTION
 
+B<Net::Travel::DE::VRR::Route::Part> holds one specific connection (without
+interchanges) between two points.  It specifies the start/stop point and time,
+the train line and its destination, and optional additional data.
+
+It is usually obtained by a call to Net::Travel::DE::VRR::Route(3pm)'s
+B<parts> method.
+
 =head1 METHODS
 
 =over
 
+=item $part = Net::Travel::DE::VRR::Route::Part->new(I<%data>)
+
+Creates a new Net::Travel::DE::VRR::Route::Part object. I<data> consists of:
+
+=over
+
+=item B<arrival_time> => I<HH>:I<MM>
+
+Arrival time
+
+=item B<arrival_stop> => I<name>
+
+Arrival stop (city plus station / address)
+
+=item B<departure_time> => I<HH:MM>
+
+Departure time
+
+=item B<departure_stop> => I<name>
+
+Departure stop (city plus station / address)
+
+=item B<train_destination> => I<name>
+
+Destination of the train connecting the stops
+
+=item B<train_line> => I<name>
+
+The train's line name.
+
+=item B<extra> => B<[> [ I<line1>, [ I<line2> [ I<...> ] ] ] B<]>
+
+Additional information about this connection.  Array-ref of newline-terminated
+strings.
+
+=back
+
+=item $part->get(I<name>)
+
+Returns the value of I<name> (B<arrival_time>, B<arrival_stop> etc., see
+B<new>).
+
+Each of these I<names> also has an accessor. So C<< $part->departure_time() >>
+is the same as C<< $part->get('departure_time') >>.
+
+=item $part->extra()
+
+Returns a list of additional information about this route part, if provided.
+Returns an empty list otherwise.
+
 =back
 
 =head1 DIAGNOSTICS
 
+None.
+
 =head1 DEPENDENCIES
 
 =over
 
+=item * Class::Accessor(3pm)
+
 =back
 
 =head1 BUGS AND LIMITATIONS
 
+None known.
+
 =head1 SEE ALSO
 
+Net::Travel::DE::VRR(3pm).
+
 =head1 AUTHOR
 
 Copyright (C) 2011 by Daniel Friesel E<lt>derf@finalrewind.orgE<gt>
-- 
cgit v1.2.3