parts/inc/ppphbin: Add comments

(cherry picked from commit 9e8dd684615d93294c81a4bff7e7610b0621d1fe)
Signed-off-by: Nicolas R <atoomic@cpan.org>

diff --git a/dist/Devel-PPPort/parts/inc/ppphbin b/dist/Devel-PPPort/parts/inc/ppphbin
index ac04f81..702a4cc 100644 (file)
--- a/dist/Devel-PPPort/parts/inc/ppphbin
+++ b/dist/Devel-PPPort/parts/inc/ppphbin
@@ -66,6 +66,12 @@ strip() if $opt{strip};
 $opt{'compat-version'} = __MIN_PERL__ unless exists $opt{'compat-version'};
 $opt{'compat-version'} = int_parse_version($opt{'compat-version'});
 
+# Each element of this hash looks something like:
+# 'Poison' => {
+#                         'base' => '5.008000',
+#                         'provided' => 1,
+#                         'todo' => '5.003007'
+#             },
 my %API = map { /^(\w+)\|([^|]*)\|([^|]*)\|(\w*)$/
                 ? ( $1 => {
                       ($2                  ? ( base     => $2 ) : ()),
@@ -97,7 +103,7 @@ if (exists $opt{'list-unsupported'}) {
   exit 0;
 }
 
-# Scan for possible replacement candidates
+# Scan for hints, possible replacement candidates, etc.
 
 my(%replace, %need, %hints, %warnings, %depends);
 my $replace = 0;
@@ -166,11 +172,14 @@ while (<DATA>) {
       next;
   }
 
-  if ($define) {
+  if ($define) { # If in the middle of a definition...
+
+    # append a continuation line ending with backslash.
     if ($define->[1] =~ /\\$/) {
       $define->[1] .= $_;
     }
-    else {
+    else {  # Otherwise this line ends the definition, make foo depend on bar
+            # (and what bar depends on) if its not one of ppp's own constructs
       if (exists $API{$define->[0]} && $define->[1] !~ /^DPPP_\(/) {
         my @n = find_api($define->[1]);
         push @{$depends{$define->[0]}}, @n if @n
@@ -179,6 +188,8 @@ while (<DATA>) {
     }
   }
 
+  # For '#define foo bar' or '#define foo(a,b,c) bar', $define becomes a
+  # reference to [ foo, bar ]
   $define = [$1, $2] if m{^\s*#\s*define\s+(\w+)(?:\([^)]*\))?\s+(.*)};
 
   if ($function) {
@@ -196,11 +207,29 @@ while (<DATA>) {
 
   $function = [$1, ''] if m{^DPPP_\(my_(\w+)\)};
 
+  # Set $replace to the number given for lines that look like
+  # / * Replace: \d+ * /
+  # (blanks added to keep real C comments from appearing in this file)
+  # Thus setting it to 1 starts a region where replacements are automatically
+  # done, and setting it to 0 ends that region.
   $replace     = $1 if m{^\s*$rccs\s+Replace:\s+(\d+)\s+$rcce\s*$};
+
+  # Add bar => foo to %replace  for lines like '#define foo bar in a region
+  # where $replace is non-zero
   $replace{$2} = $1 if $replace and m{^\s*#\s*define\s+(\w+)(?:\([^)]*\))?\s+(\w+)};
+
+  # Add bar => foo to %replace for lines like '#define foo bar  / * Replace * /
+  # (blanks added to keep real C comments from appearing in this file)
   $replace{$2} = $1 if m{^\s*#\s*define\s+(\w+)(?:\([^)]*\))?\s+(\w+).*$rccs\s+Replace\s+$rcce};
+
+  # Add foo => bar to %replace for lines like / * Replace foo with bar * /
+  # (blanks added to keep real C comments from appearing in this file)
   $replace{$1} = $2 if m{^\s*$rccs\s+Replace (\w+) with (\w+)\s+$rcce\s*$};
 
+  # For lines like / * foo, bar depends on baz, bat * /
+  # create a list of the elements on the rhs, and make that list apply to each
+  # element in the lhs, which becomes a key in \%depends.
+  # (blanks added to keep real C comments from appearing in this file)
   if (m{^\s*$rccs\s+(\w+(\s*,\s*\w+)*)\s+depends\s+on\s+(\w+(\s*,\s*\w+)*)\s+$rcce\s*$}) {
     my @deps = map { s/\s+//g; $_ } split /,/, $3;
     my $d;