From e2445f36615980742259c5e54c93b8c272a144c0 Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@finalrewind.org>
Date: Sat, 22 Oct 2022 20:02:41 +0200
Subject: HAFAS: Document ->messages; sort functions

---
 lib/Travel/Status/DE/HAFAS.pm | 98 ++++++++++++++++++++++++++-----------------
 1 file changed, 59 insertions(+), 39 deletions(-)

(limited to 'lib/Travel')

diff --git a/lib/Travel/Status/DE/HAFAS.pm b/lib/Travel/Status/DE/HAFAS.pm
index 0713876..ecc86bc 100644
--- a/lib/Travel/Status/DE/HAFAS.pm
+++ b/lib/Travel/Status/DE/HAFAS.pm
@@ -1,5 +1,7 @@
 package Travel::Status::DE::HAFAS;
 
+# vim:foldmethod=marker
+
 use strict;
 use warnings;
 use 5.014;
@@ -23,6 +25,8 @@ use Travel::Status::DE::HAFAS::StopFinder;
 
 our $VERSION = '3.01';
 
+# {{{ Endpoint Definition
+
 my %hafas_instance = (
 	DB => {
 		stopfinder  => 'https://reiseauskunft.bahn.de/bin/ajax-getstop.exe',
@@ -175,6 +179,9 @@ my %hafas_instance = (
 	},
 );
 
+# }}}
+# {{{ Constructors
+
 sub new {
 	my ( $obj, %conf ) = @_;
 	my $service = $conf{service};
@@ -400,6 +407,9 @@ sub new_p {
 	return $promise;
 }
 
+# }}}
+# {{{ Internal Helpers
+
 sub post_with_cache {
 	my ( $self, $url ) = @_;
 	my $cache = $self->{cache};
@@ -519,40 +529,6 @@ sub check_mgate {
 	return $self;
 }
 
-sub errcode {
-	my ($self) = @_;
-
-	return $self->{errcode};
-}
-
-sub errstr {
-	my ($self) = @_;
-
-	return $self->{errstr};
-}
-
-sub similar_stops {
-	my ($self) = @_;
-
-	my $service = $self->{active_service};
-
-	if ( $service and exists $hafas_instance{$service}{stopfinder} ) {
-
-		my $sf = Travel::Status::DE::HAFAS::StopFinder->new(
-			url            => $hafas_instance{$service}{stopfinder},
-			input          => $self->{station},
-			ua             => $self->{ua},
-			developer_mode => $self->{developer_mode},
-		);
-		if ( my $err = $sf->errstr ) {
-			$self->{errstr} = $err;
-			return;
-		}
-		return $sf->results;
-	}
-	return;
-}
-
 sub add_message {
 	my ( $self, $json, $is_him ) = @_;
 
@@ -590,11 +566,6 @@ sub add_message {
 	return $message;
 }
 
-sub messages {
-	my ($self) = @_;
-	return @{ $self->{messages} };
-}
-
 sub parse_journey {
 	my ($self) = @_;
 
@@ -649,6 +620,48 @@ sub parse_board {
 	return $self;
 }
 
+# }}}
+# {{{ Public Functions
+
+sub errcode {
+	my ($self) = @_;
+
+	return $self->{errcode};
+}
+
+sub errstr {
+	my ($self) = @_;
+
+	return $self->{errstr};
+}
+
+sub similar_stops {
+	my ($self) = @_;
+
+	my $service = $self->{active_service};
+
+	if ( $service and exists $hafas_instance{$service}{stopfinder} ) {
+
+		my $sf = Travel::Status::DE::HAFAS::StopFinder->new(
+			url            => $hafas_instance{$service}{stopfinder},
+			input          => $self->{station},
+			ua             => $self->{ua},
+			developer_mode => $self->{developer_mode},
+		);
+		if ( my $err = $sf->errstr ) {
+			$self->{errstr} = $err;
+			return;
+		}
+		return $sf->results;
+	}
+	return;
+}
+
+sub messages {
+	my ($self) = @_;
+	return @{ $self->{messages} };
+}
+
 sub results {
 	my ($self) = @_;
 	return @{ $self->{results} };
@@ -689,6 +702,8 @@ sub get_active_service {
 	return;
 }
 
+# }}}
+
 1;
 
 __END__
@@ -856,6 +871,11 @@ the requested journey. Unavailable in station board mode.
 
 If no result was found or the parser / http request failed, returns undef.
 
+=item $status->messages
+
+Returns a list of Travel::Status::DE::HAFAS::Message(3pm) objects with
+service messages. Each message belongs to at least one arrival/departure.
+
 =item $status->similar_stops
 
 Returns a list of hashrefs describing stops whose name is similar to the one
-- 
cgit v1.2.3