DBRIS: Add documentation

1 files changed, 158 insertions, 1 deletions

diff --git a/lib/Travel/Routing/DE/DBRIS.pm b/lib/Travel/Routing/DE/DBRIS.pm
index deba8ad..70b71ba 100644
--- a/lib/Travel/Routing/DE/DBRIS.pm
+++ b/lib/Travel/Routing/DE/DBRIS.pm
@@ -25,7 +25,6 @@ Travel::Routing::DE::DBRIS->mk_ro_accessors(qw(earlier later));
 
 sub new {
 	my ( $obj, %conf ) = @_;
-	my $service = $conf{service};
 
 	my $ua = $conf{user_agent};
 
@@ -278,3 +277,161 @@ sub connections {
 # }}}
 
 1;
+
+__END__
+
+=head1 NAME
+
+Travel::Routing::DE::DBRIS - Interface to the bahn.de itinerary service
+
+=head1 SYNOPSIS
+
+	use Travel::Routing::DE::DBRIS;
+
+	# use Travel::Status::DE::DBRIS to obtain $from and $to objects
+	# (must be Travel::Status::DE::DBRIS::Location instances)
+
+	my $ris = Travel::Routing::DE::DBRIS->new(
+		from => $from_location,
+		to => $to_location,
+	);
+
+	if (my $err = $ris->errstr) {
+		die("Request error: ${err}\n");
+	}
+
+	for my $con ( $ris->connections ) {
+		for my $seg ($con->segments) {
+			if ( not ($seg->is_transfer or $seg->is_walk) ) {
+				printf("%s -> %s\n%s ab %s\n%s an %s\n\n",
+					$seg->train_mid,
+					$seg->direction,
+					$seg->dep->strftime('%H:%M'),
+					$seg->dep_name,
+					$seg->arr->strftime('%H:%M'),
+					$seg->arr_name,
+				);
+			}
+		}
+		print "\n\n";
+	}
+
+=head1 VERSION
+
+version 0.01
+
+=head1 DESCRIPTION
+
+Travel::Routing::DE::DBRIS is an interface to the bahn.de itinerary service.
+
+=head1 METHODS
+
+=over
+
+=item $ris = Travel::Routing::DE::DBRIS->new(I<%opt>)
+
+Request connections as specified by I<%opt> and return a new
+Travel::Routing::DE::DBRIS instance with the results. Dies if the wrong I<%opt>
+were passed. The B<origin> and B<destination> keys are mandatory.
+
+=over
+
+=item B<origin> => I<stop> (mandatory)
+
+A Travel::Status::DE::DBRIS::Location(3pm) instance describing the origin of
+the requested itinerary.
+
+=item B<destination> => I<stop> (mandatory)
+
+A Travel::Status::DE::DBRIS::Location(3pm) instance describing the destination
+of the requested itinerary.
+
+=item B<cache> => I<cache>
+
+A Cache::File(3pm) instance used for caching bahn.de requests.
+
+=item B<datetime> => I<datetime>
+
+Request departures on or after I<datetime> (DateTime(3pm) instance).
+Default: now.
+
+=item B<language> => I<lang>
+
+Request text components to be provided in I<lang> (ISO 639-1 language code).
+Known supported languages are: cs da de en es fr it nl pl.
+Default: de.
+
+=item B<modes_of_transit> => I<arrayref>
+
+Only request connections using the modes of transit specified in I<arrayref>.
+Default: ICE, EC_IC, IR, REGIONAL, SBAHN, BUS, SCHIFF, UBAHN, TRAM, ANRUFPFLICHTIG.
+
+=item B<discounts> => I<arrayref>
+
+Consider discounts specified in I<arrayref> when determining offer prices.
+Supported items: bc25, bs25-first, bc50, bc50-first, bc100, bc100-first.
+Default: none.
+
+=item B<user_agent> => I<user agent>
+
+Use I<user agent> for requests.
+Default: A new LWP::UserAgent(3pm) object with env_proxy enabled and a timeout
+of ten seconds.
+
+=item B<lwp_options> => I<hashref>
+
+Pass I<hashref> to C<< LWP::UserAgent->new >>.
+Default: C<< { timeout => 10 } >>.
+
+=back
+
+=item $ris->errstr
+
+Returns a string describing a HTTP or bahn.de error, if any such error occured.
+Returns undef otherwise.
+
+=item $ris->connections
+
+Returns a list of Travel::Routing::DE::DBRIS::Connection(3pm) objects, each of
+which describes a singre connction from I<origin> to I<destination>.
+
+=back
+
+=head1 DIAGNOSTICS
+
+when the B<developer_mode> argument to B<new> is set to a true value,
+Travel::Routing::DE::DBRIS prints raw bahn.de requests and responses to stdout.
+
+None.
+
+=head1 DEPENDENCIES
+
+=over
+
+=item * Class::Accessor(3pm)
+
+=item * DateTime(3pm)
+
+=item * DateTime::Format::Strptime(3pm)
+
+=item * LWP::UserAgent(3pm)
+
+=item * Travel::Status::DE::DBRIS(3pm)
+
+=back
+
+=head1 BUGS AND LIMITATIONS
+
+This module is very much work-in-progress.
+
+=head1 SEE ALSO
+
+Travel::Routing::DE::DBRIS::Connection(3pm)
+
+=head1 AUTHOR
+
+Copyright (C) 2025 by Birte Kristina Friesel E<lt>derf@finalrewind.orgE<gt>
+
+=head1 LICENSE
+
+This module is licensed under the same terms as Perl itself.