From 80fe6325cfdbd6d2434f55f7aa728502fb3ec6b6 Mon Sep 17 00:00:00 2001
From: Sergey Matveev <stargrave@stargrave.org>
Date: Thu, 15 May 2025 12:32:48 +0300
Subject: [PATCH] perlcritic on docstringer

---
 bin/bin/docstringer.pl | 86 ++++++++++++++++++++++++++++--------------
 1 file changed, 58 insertions(+), 28 deletions(-)

diff --git a/bin/bin/docstringer.pl b/bin/bin/docstringer.pl
index aa2c335..1e3f1e1 100755
--- a/bin/bin/docstringer.pl
+++ b/bin/bin/docstringer.pl
@@ -1,7 +1,7 @@
 #!/usr/bin/env perl
 # Simple script for substitute placeholders in Texinfo files with
 # docstring values found in source code.
-# Copyright (C) 2020-2025 Sergey Matveev (stargrave@stargrave.org)
+# Copyright (C) 2020-2025 Sergey Matveev <stargrave@stargrave.org>
 #
 # If you C source code contains:
 #
@@ -18,26 +18,33 @@
 
 use strict;
 use warnings;
+use Carp q{croak};
 
 my $verbose = 0;
-if ($ARGV[0] eq "-v") {
+if ($ARGV[0] eq q{-v}) {
     $verbose = 1;
     shift @ARGV;
 }
 my $outDir = $ARGV[0];
 my @srcDirs = split /:/, $ARGV[1];
 my @docDirs = split /:/, $ARGV[2];
-my @exts = split / /, (defined $ENV{EXTS}) ? $ENV{EXTS} : "c h h.in";
-
+my @exts = (defined $ENV{EXTS}) ? (split / /, $ENV{EXTS}) : qw{c h h.in};
 my %docstrings;
 
 foreach my $srcDir (@srcDirs) {
-    print "src: $srcDir\n" if $verbose;
-    opendir(my $dir, $srcDir) or die "can not open $srcDir";
+    if ($verbose) {
+        print "src: $srcDir\n";
+    }
+    opendir my $dir, $srcDir or croak "can not open $srcDir";
     foreach my $fn (readdir $dir) {
-        next unless grep { $fn =~ /\.$_$/ } @exts;
-        open(my $src, "<:encoding(UTF-8)", "$srcDir/$fn") or
-            die "can not open $srcDir/$fn";
+        foreach (@exts) {
+            if ($fn =~ /[.]$_$/) {
+                goto ExtIsGood;
+            }
+        }
+        next;
+    ExtIsGood:
+        open my $src, q{<:encoding(UTF-8)}, "$srcDir/$fn" or croak "can not open $srcDir/$fn";
         my $curEntry;
         while (<$src>) {
             chomp;
@@ -47,40 +54,63 @@ foreach my $srcDir (@srcDirs) {
                 }
                 next;
             }
-            s/^\/\/ ?//;
+            s/^\/\/[ ]?//;
             if (/^TEXINFO: (.*)$/) {
                 $curEntry = $1;
-                $docstrings{$curEntry} = "";
-                print "\t$fn: $curEntry\n" if $verbose;
+                $docstrings{$curEntry} = q{};
+                if ($verbose) {
+                    print "\t$fn: $curEntry\n";
+                }
                 next;
             }
-            ($docstrings{$curEntry} .= "$_\n") if defined $curEntry;
+            if (defined $curEntry) {
+                $docstrings{$curEntry} .= "$_\n";
+            }
         }
-        close $src;
+        close $src or croak "$!";
     }
     closedir $dir;
 }
 
 foreach my $docDir (@docDirs) {
-    print "doc: $docDir\n" if $verbose;
-    opendir(my $dir, $docDir) or die "can not open $docDir";
-    ($docDir .= "/") unless $docDir =~ /\/$/;
-    ($docDir = "") if $docDir eq "./";
+    if ($verbose) {
+        print "doc: $docDir\n";
+    }
+    opendir my $dir, $docDir or croak "can not open $docDir";
+    if ($docDir !~ /[\/]$/) {
+        $docDir .= q{/};
+    }
+    if ($docDir eq q{./}) {
+        $docDir = q{};
+    }
     foreach my $fn (readdir $dir) {
-        next unless $fn =~ /\.texi$/;
+        if ($fn !~ /[.]texi$/) {
+            next;
+        }
         $fn = $docDir . $fn;
-        open(my $src, "<:encoding(UTF-8)", $fn) or die "can not open $fn";
+        open my $src, q{<:encoding(UTF-8)}, $fn or croak "can not open $fn";
         mkdir "$outDir/$docDir";
-        open(my $dst, ">:encoding(UTF-8)", "$outDir/$fn") or
-            die "can not open $outDir/$fn";
+        open my $dst, q{>:encoding(UTF-8)}, "$outDir/$fn" or
+            croak "can not open $outDir/$fn";
+        my $ref;
         while (<$src>) {
-            (print($dst $_) and next) unless /^\s*\@DOCSTRING (.*)\@$/;
-            print "\t$fn: $1\n" if $verbose;
-            die "unable to find docstring: $1" unless defined $docstrings{$1};
-            print $dst $docstrings{$1};
+            if (/^\s*\@DOCSTRING (.*)\@$/) {
+                $ref = $1;
+            } else {
+                print {$dst} $_;
+                next;
+            }
+            if ($verbose) {
+                print "\t$fn: $ref\n";
+            }
+            if (defined $docstrings{$ref}) {
+                print {$dst} $docstrings{$ref};
+            } else {
+                croak "unable to find docstring: $ref";
+            }
         }
-        close $src;
-        close $dst;
+        close $src or croak "$!";
+        close $dst or croak "$!";
     }
     closedir $dir;
 }
-- 
2.48.1