More descriptive accessor names in Net::Travel::DE::VRR::Route::Part

3 files changed, 121 insertions, 38 deletions

diff --git a/lib/Net/Travel/DE/VRR.pm b/lib/Net/Travel/DE/VRR.pm
index 7948194..8f1b506 100644
--- a/lib/Net/Travel/DE/VRR.pm
+++ b/lib/Net/Travel/DE/VRR.pm
@@ -360,16 +360,16 @@ sub parse_pretty {
 			push( @{ $hash->{extra} }, $extra );
 		}
 
-		$hash->{dep_time} = $con->[0];
+		$hash->{departure_time} = $con->[0];
 
 		# always "ab"           $con->[1];
-		$hash->{dep_stop}   = $con->[2];
-		$hash->{train_line} = $con->[3];
-		$hash->{arr_time}   = $con->[4];
+		$hash->{departure_stop} = $con->[2];
+		$hash->{train_line}     = $con->[3];
+		$hash->{arrival_time}   = $con->[4];
 
-		# always "an"           $con->[5];
-		$hash->{arr_stop}   = $con->[6];
-		$hash->{train_dest} = $con->[7];
+		# always "an"                $con->[5];
+		$hash->{arrival_stop}      = $con->[6];
+		$hash->{train_destination} = $con->[7];
 
 		push( @elements, $hash );
 	}
@@ -605,33 +605,8 @@ returns a true value on success.
 
 =item $efa->routes()
 
-Returns an array of connection elements. Each connection element is an
-arrayref of connection part, and each connecton part is a hash containing the
-following elements:
-
-=over
-
-=item * dep_time
-
-Departure time as a string in HH:MM format
-
-=item * dep_stop
-
-Departure stop, e.g. "Essen HBf"
-
-=item * train_line
-
-Name of the train line, e.g. "S-Bahn S6"
-
-=item * arr_time
-
-Arrival time as a string in HH:MM format
-
-=item * arr_stop
-
-Arrival stop, e.g. "Berlin HBf"
-
-=back
+Returns a list of Net::Travel::DE::VRR::Route(3pm) elements. Each one contains
+one method of getting from start to stop.
 
 =back
 
diff --git a/lib/Net/Travel/DE/VRR/Route.pm b/lib/Net/Travel/DE/VRR/Route.pm
index 1b71097..7089120 100644
--- a/lib/Net/Travel/DE/VRR/Route.pm
+++ b/lib/Net/Travel/DE/VRR/Route.pm
@@ -39,30 +39,57 @@ Net::Travel::DE::VRR::Route - Single route (connection) between two points
 
 =head1 SYNOPSIS
 
+	for my $route ( $efa->routes() ) {
+		for my $part ( $route->parts() ) {
+			# $part is a Net::Travel::DE::VRR::Route::Part object
+		}
+	}
+
 =head1 VERSION
 
 version 1.3
 
 =head1 DESCRIPTION
 
+Net::Travel::DE::VRR::Route describes a single method of getting from one
+point to another.  It holds a bunch of Net::Travel::DE::VRR::Route::Part(3pm)
+objects describing the parts of the route in detail.  Each part depends on the
+previous one.
+
+You usually want to acces it via C<< $efa->routes() >>.
+
 =head1 METHODS
 
 =over
 
+=item my $route = Net::Travel::DE::VRR::Route->new(I<@parts>)
+
+Creates a new Net::Travel::DE::VRR::Route elements consisting of I<parts>,
+which are Net::Travel::DE::VRR::Route::Part elements.
+
+=item $route->parts()
+
+Returns a list of Net::Travel::DE::VRR::Route::Part(3pm) elements describing
+the actual route.
+
 =back
 
 =head1 DIAGNOSTICS
 
+None.
+
 =head1 DEPENDENCIES
 
-=over
-
-=back
+None.
 
 =head1 BUGS AND LIMITATIONS
 
+None known.
+
 =head1 SEE ALSO
 
+Net::Travel::DE::VRR(3pm), Net::Travel::DE::VRR::Route::Part(3pm).
+
 =head1 AUTHOR
 
 Copyright (C) 2011 by Daniel Friesel E<lt>derf@finalrewind.orgE<gt>
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>