From 432f75530932266412c76da42ac214a516197f9b Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@finalrewind.org>
Date: Thu, 12 May 2016 12:52:18 +0200
Subject: Update Stations.pm documentation

---
 lib/Travel/Status/DE/IRIS/Stations.pm | 63 +++++++++++++++++++++++++----------
 1 file changed, 45 insertions(+), 18 deletions(-)

diff --git a/lib/Travel/Status/DE/IRIS/Stations.pm b/lib/Travel/Status/DE/IRIS/Stations.pm
index ea2a6fc..7a17985 100644
--- a/lib/Travel/Status/DE/IRIS/Stations.pm
+++ b/lib/Travel/Status/DE/IRIS/Stations.pm
@@ -8493,7 +8493,7 @@ sub get_station {
 	return get_station_by_name($name);
 }
 
-sub get_stations_by_location {
+sub get_station_by_location {
 	my ( $lon, $lat, $num_matches ) = @_;
 
 	$num_matches //= 10;
@@ -8580,28 +8580,42 @@ version 0.00
 
 =head1 DESCRIPTION
 
-This module contains a mapping of DeutscheBahn station names to station codes.
-A station name is a (perhaps slightly abbreviated) string naming a particular
-station; a station code is a two to five character denoting a station for the
-IRIS web service.
+This module contains a list of Deutsche Bahn stations, and also some stations
+outside of Germany which are served by Deutsche Bahn trains. It offers
+several accessors to look up stations based on names or geolocation data and
+can also simply dump all known stations.
 
-Example station names (code in parentheses) are:
-"Essen HBf" (EE), "Aachen Schanz" (KASZ), "Do UniversitE<auml>t" (EDUV).
+Each of the following methods returns a list of array references. Each
+array reference describes a single station and contains either two or
+five elements:
 
-B<Note:> Station codes may contain whitespace.
+=over
+
+=item * The station code (also known as DS100 / "Druckschrift 100" /
+"Richtlinie 100"). A short string used exclusively by Deutsche Bahn APIs. Note
+that it may contain space characters.
+
+=item * The station name
+
+=item * The international station number (IBNR, "Internationale Bahnhofsnummer")
+
+=item * The station's longitude
+
+=item * The station's latitude
+
+=back
 
 =head1 METHODS
 
 =over
 
-=item Travel::Status::DE::IRIS::get_stations
+=item Travel::Status::DE::IRIS::Stations::get_stations
 
-Returns a list of [station code, station name] listrefs lexically sorted by
-station name.
+Returns a list of all known stations, lexically sorted by station name.
 
-=item Travel::Status::DE::IRIS::get_station(I<$in>)
+=item Travel::Status::DE::IRIS::Stations::get_station(I<$in>)
 
-Returns a list of [station code, station name] listrefs matching I<$in>.
+Returns a list of stations matching I<$in>.
 
 If a I<$in> is a valid station code, only one element ([I<$in>, related name])
 is returned. Otherwise, it is passed to get_station_by_name(I<$in>) (see
@@ -8609,16 +8623,27 @@ below).
 
 Note that station codes matching is case sensitive and must be exact.
 
-=item Travel::Status::DE::IRIS::get_station_by_name(I<$name>)
+=item Travel::Status::DE::IRIS::Stations::get_station_by_location(I<$lon>, I<$lat>, I<$num_matches>)
+
+Looks for stations which are close to longitude/latitude I<$lon>/I<$lat> and
+returns the closest I<$num_matches> (defaults to 10) matches. Note that
+stations which are located more than 70 kilometers away from I<$lon>/I<$lat>
+may be ignored when computing the closest matches.
 
-Returns a list of [station code, station name] listrefs where the station
-name matches I<$name>.
+Note that location-based lookup is only supported for stations inside Germany,
+since the station list data source does not provide geolocation data for
+non-german stations.
+
+=item Travel::Status::DE::IRIS::Stations::get_station_by_name(I<$name>)
+
+Returns a list of stations where the station name matches I<$name>.
 
 Matching happens in two steps: If a case-insensitive exact match exists, only
 this one is returned. Otherwise, all stations whose name contains I<$name> as
-a substring (also case-insensitive) are returned.
+a substring (also case-insensitive) and all stations whose name has a low
+Levenshtein distance to I<$name> are returned.
 
-This two-step behaviour makes sure that not prefix-free stations can still be
+This two-step behaviour makes sure that not-prefix-free stations can still be
 matched directly. For instance, both "Essen-Steele" and "Essen-Steele Ost"
 are valid station names, but "essen-steele" will only return "Essen-Steele".
 
@@ -8632,6 +8657,8 @@ None.
 
 =over
 
+=item * Geo::Distance(3pm)
+
 =item * List::MoreUtils(3pm)
 
 =item * List::Util(3pm)
-- 
cgit v1.2.3