code cleanup (mainly improving comments)

diff --git a/PLP.pm b/PLP.pm
index 8826b28ae3eb577ca4fbc53c27a57e705389b3be..c78af4163f560d7ef16feb7ebe4fd104aa2431bc 100644 (file)
--- a/PLP.pm
+++ b/PLP.pm
@@ -1,6 +1,4 @@
-#--------------#
-  package PLP;
-#--------------#
+package PLP;
 
 use v5.6;
 
@@ -36,24 +34,18 @@ sub sendheaders () {
     our $sentheaders = 1;
     print STDOUT "Content-Type: text/plain\n\n" if $PLP::DEBUG & 2;
     print STDOUT map("$_: $PLP::Script::header{$_}\n", keys %PLP::Script::header), "\n";
-};
+}
 
-# Given a filename and optional level (level should be 0 if the caller isn't
-# source() itself), and optional linespec (used by PLP::Functions::Include),
-# this function parses a PLP file and returns Perl code, ready to be eval'ed
 {
-    my %cached; # Conceal cached sources
-    
-    # %cached = (
-    #  $filename => [
-    #      [ dependency, dependency, dependency ], # <(...)>
-    #      'source',
-    #      -M
-    #  ]
-    # );
+    my %cached; # Conceal cached sources: ( path => [ [ deps ], source, -M ] )
     
+    # Given a filename and optional level (level should be 0 if the caller isn't
+    # source() itself), and optional linespec (used by PLP::Functions::Include),
+    # this function parses a PLP file and returns Perl code, ready to be eval'ed
     sub source {
        my ($file, $level, $linespec, $path) = @_;
+       # $file is displayed, $path is used. $path is constructed from $file if
+       # not given.
        $level = 0      if not defined $level;
        $linespec = '1' if not defined $linespec;
        
@@ -150,8 +142,7 @@ sub sendheaders () {
     }
 }
 
-# Handles errors, uses the sub reference $PLP::ERROR that gets two arguments:
-# the error message in plain text, and the error message with html entities
+# Handles errors, uses subref $PLP::ERROR (default: \&_default_error)
 sub error {
     my ($error, $type) = @_;
     if (not defined $type or $type < 100) {
@@ -204,8 +195,7 @@ sub clean {
 #  o  Set $ENV{PLP_*} and makes PATH_INFO if needed
 #  o  Change the CWD
 
-# This sub is meant for CGI requests only, and takes apart PATH_TRANSLATED
-# to find the file.
+# CGI initializer: parses PATH_TRANSLATED
 sub cgi_init {
     my $path = $ENV{PATH_TRANSLATED};
     $ENV{PLP_NAME} = $ENV{PATH_INFO};
@@ -240,8 +230,7 @@ sub cgi_init {
     $PLP::code = PLP::source($file, 0, undef, $path);
 }
 
-# This is the mod_perl initializer.
-# Returns 0 on success.
+# mod_perl initializer: returns 0 on success, Apache error code on failure
 sub mod_perl_init {
     my $r = shift;
     
@@ -294,11 +283,7 @@ sub start {
 #    The above does not work. TODO - find out why not.
 }
 
-# This is run by the CGI script.
-# The CGI script is just:
-#   #!/usr/bin/perl
-#   use PLP;
-#   PLP::everything();
+# This is run by the CGI script. (#!perl \n use PLP; PLP::everything;)
 sub everything {
     clean();
     cgi_init();
@@ -487,7 +472,9 @@ efficiency. To set headers, you must assign to C<$header{ $header_name}> before
 any output. This means the opening C<< <: >> have to be the first characters in
 your document, without any whitespace in front of them. If you start output and
 try to set headers later, an error message will appear telling you on which
-line your output started.
+line your output started. An alternative way of setting headers is using Perl's
+BEGIN blocks. BEGIN blocks are executed as soon as possible, before anything
+else.
 
 Because the interpreter that mod_perl uses never ends, C<END { }> blocks won't
 work properly. You should use C<PLP_END { };> instead. Note that this is a not

diff --git a/PLP/FAQ.pod b/PLP/FAQ.pod
index 2aac8053b54c76e11be67ac9fe783088f87c942a..da4fbe7e6d6622eb4f004219e43096e9a7ab43ab 100644 (file)
--- a/PLP/FAQ.pod
+++ b/PLP/FAQ.pod
@@ -1,4 +1,8 @@
-=head1 Frequently Asked Questions about PLP
+=head1 NAME
+
+PLP::FAQ - Frequently Asked Questions about PLP
+
+=head1 FAQ
 
 =over 10
 

diff --git a/PLP/Fields.pm b/PLP/Fields.pm
index 3c09977ef0ba9b9d427a0c9cf8d182138e9dc433..7120c06215a3f1d1910178c811ea93b453747aa9 100644 (file)
--- a/PLP/Fields.pm
+++ b/PLP/Fields.pm
@@ -1,6 +1,5 @@
-#----------------------#
-  package PLP::Fields;
-#----------------------#
+package PLP::Fields;
+
 use strict;
 
 # Has only one function: doit(), which ties the hashes %get, %post, %fields and %header in

diff --git a/PLP/Functions.pm b/PLP/Functions.pm
index debb7675c698983bad696cfb9440feba95abdd75..ea30488f55a79f280fe6fb2ce552e3b8458c5a9c 100644 (file)
--- a/PLP/Functions.pm
+++ b/PLP/Functions.pm
@@ -1,6 +1,5 @@
-#-------------------------#
-  package PLP::Functions;
-#-------------------------#
+package PLP::Functions;
+
 use base 'Exporter';
 use Fcntl qw(:flock);
 use strict;
@@ -16,7 +15,7 @@ sub Include ($) {
     local $@;
     eval 'package PLP::Script; ' . PLP::source($PLP::file, 0, join ' ', (caller)[2,1]);
     if ($@) {
-       PLP::Functions::exit if $@ =~ /\cS\cT\cO\cP/;
+       PLP::Functions::exit() if $@ =~ /\cS\cT\cO\cP/;
        PLP::error($@, 1);
     }
 }
@@ -67,9 +66,9 @@ sub Entity (@) {
     return defined wantarray ? (wantarray ? @$ref : "@$ref") : undef;
 }
 
-# Browsers do s/ /+/ - I don't care about RFC's, but I do care about real-life
-# situations.
 sub DecodeURI (@) {
+    # Browsers do s/ /+/ - I don't care about RFC's, but I do care about real-life
+    # situations.
     my @r;
     local $_;    
     for (@_) {
@@ -85,6 +84,7 @@ sub DecodeURI (@) {
     }
     return defined wantarray ? (wantarray ? @r : "@r") : undef;
 }
+
 sub EncodeURI (@) {
     my @r;
     local $_;

diff --git a/PLP/Tie/Delay.pm b/PLP/Tie/Delay.pm
index ea136b83091c835f00fbf86144d9e01f50573db1..1200651590552bfe9051b5ffe4f30316475079b2 100644 (file)
--- a/PLP/Tie/Delay.pm
+++ b/PLP/Tie/Delay.pm
@@ -1,6 +1,5 @@
-#--------------------------#
-  package PLP::Tie::Delay;
-#--------------------------#
+package PLP::Tie::Delay;
+
 use strict;
 no strict 'refs';
 
@@ -69,7 +68,7 @@ sub NEXTKEY {
 }
 
 sub UNTIE   { }
-sub DESTORY { } 
+sub DESTROY { } 
 
 1;
 

diff --git a/PLP/Tie/Headers.pm b/PLP/Tie/Headers.pm
index e8f961c0e9e31850ac5e621be9b2d1cb12242866..f6c4319827f55a95a233c8d6afd579839510cb90 100644 (file)
--- a/PLP/Tie/Headers.pm
+++ b/PLP/Tie/Headers.pm
@@ -1,6 +1,5 @@
-#----------------------------#
-  package PLP::Tie::Headers;
-#----------------------------#
+package PLP::Tie::Headers;
+
 use strict;
 use Carp;
 

diff --git a/PLP/Tie/Print.pm b/PLP/Tie/Print.pm
index 4c6983f838a3d5cfe8f0efd420a97d085dfc4fb0..3d5027a187dc2a1835190d46da87d40530975550 100644 (file)
--- a/PLP/Tie/Print.pm
+++ b/PLP/Tie/Print.pm
@@ -1,6 +1,5 @@
-#--------------------#
- package PLP::Tie::Print;
-#--------------------#
+package PLP::Tie::Print;
+
 use strict;
 
 =head1 PLP::Tie::Print