Issue #737: update POD

in order to better reflect the actual usage
RotherOSS · Jan 20, 2021 · 827062b · 827062b
1 parent c2800eb
commit 827062b
Show file tree

Hide file tree

Showing 5 changed files with 162 additions and 65 deletions.
diff --git a/Kernel/System/Web/InterfaceAgent.pm b/Kernel/System/Web/InterfaceAgent.pm
@@ -18,6 +18,9 @@ package Kernel::System::Web::InterfaceAgent;
 
 use strict;
 use warnings;
+use v5.24;
+use namespace::autoclean;
+use utf8;
 
 # core modules
 
@@ -49,34 +52,52 @@ our @ObjectDependencies = (
 
 Kernel::System::Web::InterfaceAgent - the agent web interface
 
-=head1 DESCRIPTION
+=head1 SYNOPSIS
 
-the global agent web interface (authentication, session handling, ...)
+    use Kernel::System::Web::InterfaceAgent;
 
-=head1 PUBLIC INTERFACE
+    # a Plack request handler
+    my $App = sub {
+        my $Env = shift;
 
-=head2 new()
+        my $Interface = Kernel::System::Web::InterfaceAgent->new(
+            # Debug => 1
+            PSGIEnv    => $Env,
+        );
 
-create agent web interface object. Do not use it directly, instead use:
+        # generate content (actually headers are generated as a side effect)
+        my $Content = $Interface->Content();
 
-    use Kernel::System::Web::InterfaceAgent;
+        # assuming all went well and HTML was generated
+        return [
+            '200',
+            [ 'Content-Type' => 'text/html' ],
+            $Content
+        ];
+    };
 
-    my $Interface = Kernel::System::Web::InterfaceAgent->new();
+=head1 DESCRIPTION
 
-    # with debugging enabled
-    my $Interface = Kernel::System::Web::InterfaceAgent->new(
-        Debug => 1
-    );
+This module generates the HTTP response for F<index.pl>.
+This class is meant to be used within a Plack request handler.
+See F<bin/psgi-bin/otobo.psgi> for the real live usage.
+
+=head1 PUBLIC INTERFACE
+
+=head2 new()
+
+create the web interface object for F<index.pl>.
 
 =cut
 
 sub new {
-    my ( $Type, %Param ) = @_;
+    my $Type  = shift;
+    my %Param = @_;
 
     # start with an empty hash for the new object
     my $Self = bless {}, $Type;
 
-    # get debug level
+    # set debug level
     $Self->{Debug} = $Param{Debug} || 0;
 
     # performance log

diff --git a/Kernel/System/Web/InterfaceCustomer.pm b/Kernel/System/Web/InterfaceCustomer.pm
@@ -18,6 +18,9 @@ package Kernel::System::Web::InterfaceCustomer;
 
 use strict;
 use warnings;
+use v5.24;
+use namespace::autoclean;
+use utf8;
 
 # core modules
 
@@ -51,34 +54,52 @@ our @ObjectDependencies = (
 
 Kernel::System::Web::InterfaceCustomer - the customer web interface
 
-=head1 DESCRIPTION
+=head1 SYNOPSIS
 
-the global customer web interface (authentication, session handling, ...)
+    use Kernel::System::Web::InterfaceCustomer;
 
-=head1 PUBLIC INTERFACE
+    # a Plack request handler
+    my $App = sub {
+        my $Env = shift;
 
-=head2 new()
+        my $Interface = Kernel::System::Web::InterfaceCustomer->new(
+            # Debug => 1
+            PSGIEnv    => $Env,
+        );
 
-create customer web interface object
+        # generate content (actually headers are generated as a side effect)
+        my $Content = $Interface->Content();
 
-    use Kernel::System::Web::InterfaceCustomer;
+        # assuming all went well and HTML was generated
+        return [
+            '200',
+            [ 'Content-Type' => 'text/html' ],
+            $Content
+        ];
+    };
 
-    my $Interface = Kernel::System::Web::InterfaceCustomer->new();
+=head1 DESCRIPTION
 
-    # with debugging enabled
-    my $Interface = Kernel::System::Web::InterfaceCustomer->new(
-        Debug => 1
-    );
+This module generates the HTTP response for F<customer.pl>.
+This class is meant to be used within a Plack request handler.
+See F<bin/psgi-bin/otobo.psgi> for the real live usage.
+
+=head1 PUBLIC INTERFACE
+
+=head2 new()
+
+create the web interface object for F<customer.pl>.
 
 =cut
 
 sub new {
-    my ( $Type, %Param ) = @_;
+    my $Type  = shift;
+    my %Param = @_;
 
     # start with an empty hash for the new object
     my $Self = bless {}, $Type;
 
-    # get debug level
+    # set debug level
     $Self->{Debug} = $Param{Debug} || 0;
 
     # performance log

diff --git a/Kernel/System/Web/InterfaceInstaller.pm b/Kernel/System/Web/InterfaceInstaller.pm
@@ -41,35 +41,52 @@ our @ObjectDependencies = (
 
 Kernel::System::Web::InterfaceInstaller - the installer web interface
 
+=head1 SYNOPSIS
+
+    use Kernel::System::Web::InterfaceInstaller;
+
+    # a Plack request handler
+    my $App = sub {
+        my $Env = shift;
+
+        my $Interface = Kernel::System::Web::InterfaceInstaller->new(
+            # Debug => 1
+            PSGIEnv    => $Env,
+        );
+
+        # generate content (actually headers are generated as a side effect)
+        my $Content = $Interface->Content();
+
+        # assuming all went well and HTML was generated
+        return [
+            '200',
+            [ 'Content-Type' => 'text/html' ],
+            $Content
+        ];
+    };
+
 =head1 DESCRIPTION
 
 This module generates the HTTP response for F<installer.pl>.
+This class is meant to be used within a Plack request handler.
+See F<bin/psgi-bin/otobo.psgi> for the real live usage.
 
 =head1 PUBLIC INTERFACE
 
 =head2 new()
 
-create the web interface object for 'installer.pl'.
-
-    use Kernel::System::Web::InterfaceInstaller;
-
-    my $Interface = Kernel::System::Web::InterfaceInstaller->new();
-
-    # with debugging enabled
-    my $Interface = Kernel::System::Web::InterfaceInstaller->new(
-        Debug => 1
-    );
+create the web interface object for F<installer.pl>.
 
 =cut
 
 sub new {
-    my $Type = shift;
+    my $Type  = shift;
     my %Param = @_;
 
     # start with an empty hash for the new object
     my $Self = bless {}, $Type;
 
-    # get debug level
+    # set debug level
     $Self->{Debug} = $Param{Debug} || 0;
 
     # register object params

diff --git a/Kernel/System/Web/InterfaceMigrateFromOTRS.pm b/Kernel/System/Web/InterfaceMigrateFromOTRS.pm
@@ -41,33 +41,50 @@ our @ObjectDependencies = (
 
 Kernel::System::Web::InterfaceMigrateFromOTRS - the migration web interface
 
-=head1 DESCRIPTION
+=head1 SYNOPSIS
 
-This module generates the content for F<migration.pl>.
+    use Kernel::System::Web::InterfaceMigrateFromOTRS;
 
-=head1 PUBLIC INTERFACE
+    # a Plack request handler
+    my $App = sub {
+        my $Env = shift;
 
-=head2 new()
+        my $Interface = Kernel::System::Web::InterfaceMigrateFromOTRS->new(
+            # Debug => 1
+            PSGIEnv    => $Env,
+        );
 
-create the web interface object for 'migration.pl'.
+        # generate content (actually headers are generated as a side effect)
+        my $Content = $Interface->Content();
 
-    use Kernel::System::Web::InterfaceMigrateFromOTRS;
+        # assuming all went well and HTML was generated
+        return [
+            '200',
+            [ 'Content-Type' => 'text/html' ],
+            $Content
+        ];
+    };
 
-    my $Interface = Kernel::System::Web::InterfaceMigrateFromOTRS->new();
+=head1 DESCRIPTION
 
-    # with debugging enabled
-    my $Interface = Kernel::System::Web::InterfaceMigrateFromOTRS->new(
-        Debug => 1
-    );
+This module generates the HTTP response for F<migration.pl>.
+This class is meant to be used within a Plack request handler.
+See F<bin/psgi-bin/otobo.psgi> for the real live usage.
+
+=head1 PUBLIC INTERFACE
+
+=head2 new()
+
+create the web interface object for F<migration.pl>.
 
 =cut
 
 sub new {
-    my $Class = shift;
+    my $Type  = shift;
     my %Param = @_;
 
     # start with an empty hash for the new object
-    my $Self = bless {}, $Class;
+    my $Self = bless {}, $Type;
 
     # set debug level
     $Self->{Debug} = $Param{Debug} || 0;

diff --git a/Kernel/System/Web/InterfacePublic.pm b/Kernel/System/Web/InterfacePublic.pm
@@ -18,6 +18,9 @@ package Kernel::System::Web::InterfacePublic;
 
 use strict;
 use warnings;
+use v5.24;
+use namespace::autoclean;
+use utf8;
 
 # core modules
 
@@ -39,34 +42,52 @@ our @ObjectDependencies = (
 
 Kernel::System::Web::InterfacePublic - the public web interface
 
-=head1 DESCRIPTION
+=head1 SYNOPSIS
 
-the global public web interface
+    use Kernel::System::Web::InterfacePublic;
 
-=head1 PUBLIC INTERFACE
+    # a Plack request handler
+    my $App = sub {
+        my $Env = shift;
 
-=head2 new()
+        my $Interface = Kernel::System::Web::InterfacePublic->new(
+            # Debug => 1
+            PSGIEnv    => $Env,
+        );
 
-create the web interface object for 'public.pl'.
+        # generate content (actually headers are generated as a side effect)
+        my $Content = $Interface->Content();
 
-    use Kernel::System::Web::InterfacePublic;
+        # assuming all went well and HTML was generated
+        return [
+            '200',
+            [ 'Content-Type' => 'text/html' ],
+            $Content
+        ];
+    };
+
+=head1 DESCRIPTION
 
-    my $Interface = Kernel::System::Web::InterfacePublic->new();
+This module generates the HTTP response for F<public.pl>.
+This class is meant to be used within a Plack request handler.
+See F<bin/psgi-bin/otobo.psgi> for the real live usage.
 
-    # with debugging enabled
-    my $Interface = Kernel::System::Web::InterfacePublic->new(
-        Debug => 1
-    );
+=head1 PUBLIC INTERFACE
+
+=head2 new()
+
+create the web interface object for F<public.pl>.
 
 =cut
 
 sub new {
-    my ( $Type, %Param ) = @_;
+    my $Type  = shift;
+    my %Param = @_;
 
     # start with an empty hash for the new object
     my $Self = bless {}, $Type;
 
-    # get debug level
+    # set debug level
     $Self->{Debug} = $Param{Debug} || 0;
 
     # performance log
@@ -105,8 +126,8 @@ Set headers in Kernels::System::Web::Request singleton as side effect.
 sub Content {
     my $Self = shift;
 
-    my $ParamObject = $Kernel::OM->Get('Kernel::System::Web::Request');
     my $ConfigObject = $Kernel::OM->Get('Kernel::Config');
+    my $ParamObject = $Kernel::OM->Get('Kernel::System::Web::Request');
 
     # Check if https forcing is active, and redirect if needed.
     if ( $ConfigObject->Get('HTTPSForceRedirect') ) {