perl: perl subroutine prototypes are problematic, don't use them

Basically, in perl, "subroutine prototypes" are not prototypes at all;
rather, they are a trick to allow user-defined subroutines that behave
like perl built-in functions.  For example, prototyped subroutines can
be called without parentheses, and can impose context on their arguments.

Such semantics can be useful in some selected situations, but might also
easily cause unexpected and harmful behaviours and side effects if we
try to use perl prototypes as we would use C prototypes.

See the excellent article "Far More than Everything You've Ever Wanted
to Know about Prototypes in Perl" by Tom Christiansen for more detailed
information:

    <http://www.perlmonks.org/?node_id=861966>
    <http://web.archive.org/web/20080421062920/\
     library.n0i.net/programming/perl/articles/fm_prototypes>

It is important to note that modern perl allows a non-predeclared
subroutine to be called without the '&' character, as long as its
call uses proper parentheses:

    foo 'str', 2;   # will trigger errors if foo is not predeclared
    foo('str', 2);  # ok even if foo is not predeclared
    &foo('str', 2); # ditto; but the '&' is old-style and redundant

Note also that the prototype indicating "no argument":

    sub func() { ... }

can actually be useful, and has no discernible downsides, so we'll
keep using it where it makes sense.

Also, in few, selected cases, we *want* to have subroutines behave like
perl builtins (e.g., we want the 'append_exeext' function to be able
to take a code block as first argument).  In such cases, we will of
course continue to make use of perl subroutine prototypes.

Let's finally see an example that might clarify the kind of problems the
use of subroutine prototypes in perl can cause.  This is just scratching
the surface; there are several other aspects, typically subtler and more
dangerous, that are not touched here.

If you have the prototyped subroutine definition:

    sub foo ($@)
    {
        my $s = shift;
        print "SCALAR: $s\n";
        print "ARRAY: @_\n";
    }

and call 'foo' in code like:

    @list = (-1, 0, 1);
    foo(@list);

you won't get a compile-time nor a runtime error (as a naive interpretation
of the "prototype" characterization would let you think).  Rather, the
prototype will cause the array '@list' will be coerced into scalar context
before being passed too 'foo', which means that its *length* (3) will be
passed to 'foo' as first argument; and since no further arguments are
present after '@list', that *void* will be coerced to an empty list before
being passed to 'foo'.

So code above will have the result of printing:

  SCALAR: 3
  ARRAY:

Quite tricky, and definitely a behaviour we don't want to rely on.

* automake.in: Delete most subroutine prototypes.  Fix few of the
remaining ones.  Related minor simplifications and adjustments.
* lib/gen-perl-protos: Adjust.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>

1 files changed, 117 insertions, 107 deletions

diff --git a/automake.in b/automake.in
index 70f1f670c..bbf0c880a 100644
--- a/automake.in
+++ b/automake.in
@@ -529,7 +529,7 @@ my %am_file_cache;
 # macro_define() call because SUFFIXES definitions impact
 # on $KNOWN_EXTENSIONS_PATTERN which is used used when parsing
 # the input am file.
-sub var_SUFFIXES_trigger ($$)
+sub var_SUFFIXES_trigger
 {
     my ($type, $value) = @_;
     accept_extensions (split (' ', $value));
@@ -946,23 +946,23 @@ register_language ('name' => 'java',
 # err_am ($MESSAGE, [%OPTIONS])
 # -----------------------------
 # Uncategorized errors about the current Makefile.am.
-sub err_am ($;%)
+sub err_am
 {
-  msg_am ('error', shift, @_);
+  msg_am ('error', @_);
 }
 
 # err_ac ($MESSAGE, [%OPTIONS])
 # -----------------------------
 # Uncategorized errors about configure.ac.
-sub err_ac ($;%)
+sub err_ac
 {
-  msg_ac ('error', shift, @_);
+  msg_ac ('error', @_);
 }
 
 # msg_am ($CHANNEL, $MESSAGE, [%OPTIONS])
 # ---------------------------------------
 # Messages about about the current Makefile.am.
-sub msg_am ($$;%)
+sub msg_am
 {
   my ($channel, $msg, %opts) = @_;
   msg $channel, "${am_file}.am", $msg, %opts;
@@ -971,7 +971,7 @@ sub msg_am ($$;%)
 # msg_ac ($CHANNEL, $MESSAGE, [%OPTIONS])
 # ---------------------------------------
 # Messages about about configure.ac.
-sub msg_ac ($$;%)
+sub msg_ac
 {
   my ($channel, $msg, %opts) = @_;
   msg $channel, $configure_ac, $msg, %opts;
@@ -985,7 +985,7 @@ sub msg_ac ($$;%)
 # We do this to avoid having the substitutions directly in automake.in;
 # when we do that they are sometimes removed and this causes confusion
 # and bugs.
-sub subst ($)
+sub subst
 {
     my ($text) = @_;
     return '@' . $text . '@';
@@ -1000,7 +1000,7 @@ sub subst ($)
 # If I "cd $RELDIR", then to come back, I should "cd $BACKPATH".
 # For instance 'src/foo' => '../..'.
 # Works with non strictly increasing paths, i.e., 'src/../lib' => '..'.
-sub backname ($)
+sub backname
 {
     my ($file) = @_;
     my @res;
@@ -1027,7 +1027,7 @@ sub backname ($)
 # verbose_var (NAME)
 # ------------------
 # The public variable stem used to implement silent rules.
-sub verbose_var ($)
+sub verbose_var
 {
     my ($name) = @_;
     return 'AM_V_' . $name;
@@ -1036,7 +1036,7 @@ sub verbose_var ($)
 # verbose_private_var (NAME)
 # --------------------------
 # The naming policy for the private variables for silent rules.
-sub verbose_private_var ($)
+sub verbose_private_var
 {
     my ($name) = @_;
     return 'am__v_' . $name;
@@ -1047,7 +1047,7 @@ sub verbose_private_var ($)
 # For  silent rules, setup VAR and dispatcher, to expand to
 # VAL-IF-SILENT if silent, to VAL-IF-VERBOSE (defaulting to
 # empty) if not.
-sub define_verbose_var ($$;$)
+sub define_verbose_var
 {
     my ($name, $silent_val, $verbose_val) = @_;
     $verbose_val = '' unless defined $verbose_val;
@@ -1073,13 +1073,13 @@ sub define_verbose_var ($$;$)
 # verbose_flag (NAME)
 # -------------------
 # Contents of '%VERBOSE%' variable to expand before rule command.
-sub verbose_flag ($)
+sub verbose_flag
 {
     my ($name) = @_;
     return '$(' . verbose_var ($name) . ')';
 }
 
-sub verbose_nodep_flag ($)
+sub verbose_nodep_flag
 {
     my ($name) = @_;
     return '$(' . verbose_var ($name) . subst ('am__nodep') . ')';
@@ -1096,7 +1096,7 @@ sub silent_flag ()
 # define_verbose_tagvar (NAME)
 # ----------------------------
 # Engage the needed silent rules machinery for tag NAME.
-sub define_verbose_tagvar ($)
+sub define_verbose_tagvar
 {
     my ($name) = @_;
     define_verbose_var ($name, '@echo "  '. $name . ' ' x (8 - length ($name)) . '" $@;');
@@ -1173,7 +1173,7 @@ sub handle_options ()
 # If the VAR wasn't defined conditionally, return $(VAR).
 # Otherwise we create an am__VAR_DIST variable which contains
 # all possible values, and return $(am__VAR_DIST).
-sub shadow_unconditionally ($$)
+sub shadow_unconditionally
 {
   my ($varname, $where) = @_;
   my $var = var $varname;
@@ -1190,7 +1190,7 @@ sub shadow_unconditionally ($$)
 # ----------------------------
 # Make sure each variable VAR in @LIST does not exist, suggest using AM_VAR
 # otherwise.
-sub check_user_variables (@)
+sub check_user_variables
 {
   my @dont_override = @_;
   foreach my $flag (@dont_override)
@@ -1520,7 +1520,7 @@ sub append_exeext (&$)
 # mentioned.  This is a separate function (as opposed to being inlined
 # in handle_source_transform) because it isn't always appropriate to
 # do this check.
-sub check_libobjs_sources ($$)
+sub check_libobjs_sources
 {
   my ($one_file, $unxformed) = @_;
 
@@ -1568,7 +1568,7 @@ sub check_libobjs_sources ($$)
 #     when producing explicit rules
 # Result is a list of the names of objects
 # %linkers_used will be updated with any linkers needed
-sub handle_single_transform ($$$$$%)
+sub handle_single_transform
 {
     my ($var, $topparent, $derived, $obj, $_file, %transform) = @_;
     my @files = ($_file);
@@ -1971,7 +1971,7 @@ EOF
 #
 # Result is a pair ($LINKER, $OBJVAR):
 #    $LINKER is a boolean, true if a linker is needed to deal with the objects
-sub define_objects_from_sources ($$$$$$$%)
+sub define_objects_from_sources
 {
   my ($var, $objvar, $nodefine, $one_file,
       $obj, $topparent, $where, %transform) = @_;
@@ -2005,7 +2005,7 @@ sub define_objects_from_sources ($$$$$$$%)
 #   extra arguments to pass to file_contents when producing rules
 # Return the name of the linker variable that must be used.
 # Empty return means just use 'LINK'.
-sub handle_source_transform ($$$$%)
+sub handle_source_transform
 {
     # one_file is canonical name.  unxformed is given name.  obj is
     # object extension.
@@ -2043,7 +2043,7 @@ sub handle_source_transform ($$$$%)
 	$needlinker |=
 	    define_objects_from_sources ($varname,
 					 $xpfx . $one_file . '_OBJECTS',
-					 $prefix =~ /EXTRA_/,
+					 !!($prefix =~ /EXTRA_/),
 					 $one_file, $obj, $varname, $where,
 					 DIST_SOURCE => ($prefix !~ /^nodist_/),
 					 %transform);
@@ -2127,7 +2127,7 @@ sub handle_source_transform ($$$$%)
 #   transformed name of object being built, or empty string if no object
 #   name of _LDADD/_LIBADD-type variable to examine
 # Returns 1 if LIBOBJS seen, 0 otherwise.
-sub handle_lib_objects ($$)
+sub handle_lib_objects
 {
   my ($xname, $varname) = @_;
 
@@ -2205,7 +2205,7 @@ sub handle_lib_objects ($$)
 # -------------------------------
 # Definitions common to LIBOBJS and ALLOCA.
 # VAR should be one of LIBOBJS, LTLIBOBJS, ALLOCA, or LTALLOCA.
-sub handle_LIBOBJS_or_ALLOCA ($)
+sub handle_LIBOBJS_or_ALLOCA
 {
   my ($var) = @_;
 
@@ -2244,7 +2244,7 @@ sub handle_LIBOBJS_or_ALLOCA ($)
   return $dir;
 }
 
-sub handle_LIBOBJS ($$$)
+sub handle_LIBOBJS
 {
   my ($var, $cond, $lt) = @_;
   my $myobjext = $lt ? 'lo' : 'o';
@@ -2283,7 +2283,7 @@ sub handle_LIBOBJS ($$$)
     }
 }
 
-sub handle_ALLOCA ($$$)
+sub handle_ALLOCA
 {
   my ($var, $cond, $lt) = @_;
   my $myobjext = $lt ? 'lo' : 'o';
@@ -2297,7 +2297,7 @@ sub handle_ALLOCA ($$$)
 }
 
 # Canonicalize the input parameter.
-sub canonicalize ($)
+sub canonicalize
 {
     my ($string) = @_;
     $string =~ tr/A-Za-z0-9_\@/_/c;
@@ -2307,7 +2307,7 @@ sub canonicalize ($)
 # Canonicalize a name, and check to make sure the non-canonical name
 # is never used.  Returns canonical name.  Arguments are name and a
 # list of suffixes to check for.
-sub check_canonical_spelling ($@)
+sub check_canonical_spelling
 {
   my ($name, @suffixes) = @_;
 
@@ -2893,7 +2893,7 @@ sub handle_scripts ()
 # -----------------------------
 # $OUTFILE     - name of the info file produced by $FILENAME.
 # $VFILE       - name of the version.texi file used (undef if none).
-sub scan_texinfo_file ($)
+sub scan_texinfo_file
 {
   my ($filename) = @_;
 
@@ -2948,7 +2948,7 @@ sub scan_texinfo_file ($)
 # DEST - the destination Info file
 # INSRC - whether DEST should be built in the source tree
 # DEPENDENCIES - known dependencies
-sub output_texinfo_build_rules ($$$@)
+sub output_texinfo_build_rules
 {
   my ($source, $dest, $insrc, @deps) = @_;
 
@@ -3043,7 +3043,7 @@ sub output_texinfo_build_rules ($$$@)
 # handle_texinfo_helper ($info_texinfos)
 # --------------------------------------
 # Handle all Texinfo source; helper for 'handle_texinfo'.
-sub handle_texinfo_helper ($)
+sub handle_texinfo_helper
 {
   my ($info_texinfos) = @_;
   my (@infobase, @info_deps_list, @texi_deps);
@@ -3585,7 +3585,7 @@ sub handle_tags ()
 # Return false if rule $NAME does not exist.  Otherwise,
 # declare it as phony, complete its definition (in case it is
 # conditional), and return its Automake::Rule instance.
-sub user_phony_rule ($)
+sub user_phony_rule
 {
   my ($name) = @_;
   my $rule = rule $name;
@@ -3745,7 +3745,7 @@ sub handle_dist ()
 # -------------------------------------------------------
 # Ensure $NAME is a directory (in $RELATIVE_DIR), and that it uses a sane
 # name.  Use $WHERE as a location in the diagnostic, if any.
-sub check_directory ($$;$)
+sub check_directory
 {
   my ($dir, $where, $reldir) = @_;
   $reldir = '.' unless defined $reldir;
@@ -3783,7 +3783,7 @@ sub check_directory ($$;$)
 # check_directories_in_var ($VARIABLE)
 # ------------------------------------
 # Recursively check all items in variables $VARIABLE as directories
-sub check_directories_in_var ($)
+sub check_directories_in_var
 {
   my ($var) = @_;
   $var->traverse_recursively
@@ -3854,7 +3854,7 @@ sub scan_aclocal_m4 ()
 
 
 # Helper function for 'substitute_ac_subst_variables'.
-sub substitute_ac_subst_variables_worker($)
+sub substitute_ac_subst_variables_worker
 {
   my ($token) = @_;
   return "\@$token\@" if var $token;
@@ -3865,7 +3865,7 @@ sub substitute_ac_subst_variables_worker($)
 # -------------------------------------
 # Replace any occurrence of ${FOO} in $TEXT by @FOO@ if FOO is an AC_SUBST
 # variable.
-sub substitute_ac_subst_variables ($)
+sub substitute_ac_subst_variables
 {
   my ($text) = @_;
   $text =~ s/\${([^ \t=:+{}]+)}/substitute_ac_subst_variables_worker ($1)/ge;
@@ -3880,7 +3880,7 @@ sub substitute_ac_subst_variables ($)
 # directory, then the directory part is simply replaced by $(srcdir).
 # But if the directory part is different, then $(top_srcdir) is
 # prepended.
-sub prepend_srcdir (@)
+sub prepend_srcdir
 {
   my (@inputs) = @_;
   my @newinputs;
@@ -3906,7 +3906,7 @@ sub prepend_srcdir (@)
 # rule of
 #   AC_CONFIG_FILES($OUTPUT:$INPUT[0]:$INPUTS[1]:...)
 # Also distribute $INPUTs which are not built by another AC_CONFIG_FOOs.
-sub rewrite_inputs_into_dependencies ($@)
+sub rewrite_inputs_into_dependencies
 {
   my ($file, @inputs) = @_;
   my @res = ();
@@ -3951,7 +3951,7 @@ sub rewrite_inputs_into_dependencies ($@)
 # -----------------------------------------------------------------
 # Handle remaking and configure stuff.
 # We need the name of the input file, to do proper remaking rules.
-sub handle_configure ($$$@)
+sub handle_configure
 {
   my ($makefile_am, $makefile_in, $makefile, @inputs) = @_;
 
@@ -4374,14 +4374,16 @@ sub handle_install ()
 			     ? (" \$(BUILT_SOURCES)\n"
 				. "\t\$(MAKE) \$(AM_MAKEFLAGS)")
 			     : ''),
-     'installdirs-local' => (user_phony_rule 'installdirs-local'
+     'installdirs-local' => (user_phony_rule ('installdirs-local')
 			     ? ' installdirs-local' : ''),
      am__installdirs => variable_value ('am__installdirs') || '');
 }
 
 
+# handle_all ($MAKEFILE)
+#-----------------------
 # Deal with 'all' and 'all-am'.
-sub handle_all ($)
+sub handle_all
 {
     my ($makefile) = @_;
 
@@ -4505,7 +4507,7 @@ sub do_check_merge_target ()
 }
 
 # Handle all 'clean' targets.
-sub handle_clean ($)
+sub handle_clean
 {
   my ($makefile) = @_;
 
@@ -4665,7 +4667,9 @@ sub handle_tests_dejagnu ()
     $output_rules .= file_contents ('dejagnu', new Automake::Location);
 }
 
-sub handle_per_suffix_test ($%)
+# handle_per_suffix_test ($TEST_SUFFIX, [%TRANSFORM])
+#----------------------------------------------------
+sub handle_per_suffix_test
 {
   my ($test_suffix, %transform) = @_;
   my ($pfx, $generic, $am_exeext);
@@ -4718,7 +4722,7 @@ sub handle_per_suffix_test ($%)
 # ------------------------------
 # Return true if $EXT can appear in $(TEST_EXTENSIONS), return false
 # otherwise.
-sub is_valid_test_extension ($)
+sub is_valid_test_extension
 {
   my $ext = shift;
   return 1
@@ -4966,7 +4970,7 @@ sub handle_minor_options ()
 # ------------------------------
 # Decode the Autoconf syntax for config files (files, headers, links
 # etc.).
-sub split_config_file_spec ($)
+sub split_config_file_spec
 {
   my ($spec) = @_;
   my ($output, @inputs) = split (/:/, $spec);
@@ -4983,7 +4987,7 @@ sub split_config_file_spec ($)
 # AC_CONFIG_FILES allow specifications such as Makefile:top.in:mid.in:bot.in
 # This functions returns the first *.in file for which a *.am exists.
 # It returns undef otherwise.
-sub locate_am (@)
+sub locate_am
 {
   my (@rest) = @_;
   my $input;
@@ -5004,7 +5008,7 @@ my %make_list;
 # --------------------------------------------------
 # Study $CONFIG-FILES which is the first argument to AC_CONFIG_FILES
 # (or AC_OUTPUT).
-sub scan_autoconf_config_files ($$)
+sub scan_autoconf_config_files
 {
   my ($where, $config_files) = @_;
 
@@ -5042,7 +5046,7 @@ sub scan_autoconf_config_files ($$)
 }
 
 
-sub scan_autoconf_traces ($)
+sub scan_autoconf_traces
 {
   my ($filename) = @_;
 
@@ -5545,7 +5549,7 @@ sub lang_java_rewrite
 # language, etc.  A finish function is only called if a source file of
 # the appropriate type has been seen.
 
-sub lang_vala_finish_target ($$)
+sub lang_vala_finish_target
 {
   my ($self, $name) = @_;
 
@@ -5658,7 +5662,7 @@ sub lang_vala_finish ()
 # The built .c files should be cleaned only on maintainer-clean
 # as the .c files are distributed. This function is called for each
 # .vala source file.
-sub lang_vala_target_hook ($$$$%)
+sub lang_vala_target_hook
 {
   my ($self, $aggregate, $output, $input, %transform) = @_;
 
@@ -5667,7 +5671,7 @@ sub lang_vala_target_hook ($$$$%)
 
 # This is a yacc helper which is called whenever we have decided to
 # compile a yacc file.
-sub lang_yacc_target_hook ($$$$%)
+sub lang_yacc_target_hook
 {
     my ($self, $aggregate, $output, $input, %transform) = @_;
 
@@ -5743,7 +5747,7 @@ sub lang_yacc_target_hook ($$$$%)
 
 # This is a lex helper which is called whenever we have decided to
 # compile a lex file.
-sub lang_lex_target_hook ($$$$%)
+sub lang_lex_target_hook
 {
     my ($self, $aggregate, $output, $input, %transform) = @_;
     # The GNU rules say that yacc/lex output files should be removed
@@ -5788,7 +5792,7 @@ sub lang_lex_finish ()
 # precedence.  This is lame, but something has to have global
 # knowledge in order to eliminate the conflict.  Add more linkers as
 # required.
-sub resolve_linker (%)
+sub resolve_linker
 {
     my (%linkers) = @_;
 
@@ -5800,7 +5804,7 @@ sub resolve_linker (%)
 }
 
 # Called to indicate that an extension was used.
-sub saw_extension ($)
+sub saw_extension
 {
     my ($ext) = @_;
     $extension_seen{$ext} = 1;
@@ -5810,7 +5814,7 @@ sub saw_extension ($)
 # ------------------------------
 # Register a single language.
 # Each %ATTRIBUTE is of the form ATTRIBUTE => VALUE.
-sub register_language (%)
+sub register_language
 {
   my (%option) = @_;
 
@@ -5863,7 +5867,7 @@ sub register_language (%)
 # --------------------------
 # This function is used to find a path from a user-specified suffix $EXT
 # to $OBJ or to some other suffix we recognize internally, e.g. 'cc'.
-sub derive_suffix ($$)
+sub derive_suffix
 {
   my ($source_ext, $obj) = @_;
 
@@ -5880,7 +5884,7 @@ sub derive_suffix ($$)
 
 
 # Pretty-print something and append to '$output_rules'.
-sub pretty_print_rule ($$@)
+sub pretty_print_rule
 {
     $output_rules .= makefile_wrap (shift, shift, @_);
 }
@@ -5897,7 +5901,7 @@ sub pretty_print_rule ($$@)
 # $STRING
 # make_conditional_string ($NEGATE, $COND)
 # ----------------------------------------
-sub make_conditional_string ($$)
+sub make_conditional_string
 {
   my ($negate, $cond) = @_;
   $cond = "${cond}_TRUE"
@@ -5925,7 +5929,7 @@ my %_am_macro_for_cond =
 # $COND
 # cond_stack_if ($NEGATE, $COND, $WHERE)
 # --------------------------------------
-sub cond_stack_if ($$$)
+sub cond_stack_if
 {
   my ($negate, $cond, $where) = @_;
 
@@ -5955,7 +5959,7 @@ sub cond_stack_if ($$$)
 # $COND
 # cond_stack_else ($NEGATE, $COND, $WHERE)
 # ----------------------------------------
-sub cond_stack_else ($$$)
+sub cond_stack_else
 {
   my ($negate, $cond, $where) = @_;
 
@@ -5985,7 +5989,7 @@ sub cond_stack_else ($$$)
 # $COND
 # cond_stack_endif ($NEGATE, $COND, $WHERE)
 # -----------------------------------------
-sub cond_stack_endif ($$$)
+sub cond_stack_endif
 {
   my ($negate, $cond, $where) = @_;
   my $old_cond;
@@ -6028,7 +6032,7 @@ sub cond_stack_endif ($$$)
 # string to define the variable unconditionally.  The third argument
 # is a list holding the values to use for the variable.  The value is
 # pretty printed in the output file.
-sub define_pretty_variable ($$$@)
+sub define_pretty_variable
 {
     my ($var, $cond, $where, @value) = @_;
 
@@ -6045,7 +6049,7 @@ sub define_pretty_variable ($$$@)
 # --------------------------------------
 # Define a new Automake Makefile variable VAR to VALUE, but only if
 # not already defined.
-sub define_variable ($$$)
+sub define_variable
 {
     my ($var, $value, $where) = @_;
     define_pretty_variable ($var, TRUE, $where, $value);
@@ -6067,14 +6071,14 @@ sub define_files_variable ($\@$$)
 
 # Like define_variable, but define a variable to be the configure
 # substitution by the same name.
-sub define_configure_variable ($)
+sub define_configure_variable
 {
   my ($var) = @_;
   # Some variables we do not want to output.  For instance it
   # would be a bad idea to output `U = @U@` when `@U@` can be
   # substituted as `\`.
   my $pretty = exists $ignored_configure_vars{$var} ? VAR_SILENT : VAR_ASIS;
-  Automake::Variable::define ($var, VAR_CONFIGURE, '', TRUE, subst $var,
+  Automake::Variable::define ($var, VAR_CONFIGURE, '', TRUE, subst ($var),
 			      '', $configure_vars{$var}, $pretty);
 }
 
@@ -6083,7 +6087,7 @@ sub define_configure_variable ($)
 # --------------------------------
 # Define a compiler variable.  We also handle defining the 'LT'
 # version of the command when using libtool.
-sub define_compiler_variable ($)
+sub define_compiler_variable
 {
     my ($lang) = @_;
 
@@ -6104,7 +6108,7 @@ sub define_compiler_variable ($)
 }
 
 
-sub define_linker_variable ($)
+sub define_linker_variable
 {
     my ($lang) = @_;
 
@@ -6126,7 +6130,7 @@ sub define_linker_variable ($)
     define_verbose_tagvar ($lang->lder || 'GEN');
 }
 
-sub define_per_target_linker_variable ($$)
+sub define_per_target_linker_variable
 {
   my ($linker, $target) = @_;
 
@@ -6201,7 +6205,7 @@ sub check_trailing_slash ($\$)
 # from Makefile.am into $output_trailer, or define variables as
 # appropriate.  NOTE we put rules in the trailer section.  We want
 # user rules to come after our generated stuff.
-sub read_am_file ($$$)
+sub read_am_file
 {
     my ($amfile, $where, $reldir) = @_;
     my $canon_reldir = &canonicalize ($reldir);
@@ -6514,7 +6518,10 @@ sub define_standard_variables ()
   $output_vars .= $comments . $rules;
 }
 
-sub read_main_am_file ($$)
+
+# read_main_am_file ($MAKEFILE_AM, $MAKEFILE_IN)
+# ----------------------------------------------
+sub read_main_am_file
 {
     my ($amfile, $infile) = @_;
 
@@ -6541,8 +6548,10 @@ sub read_main_am_file ($$)
 
 ################################################################
 
-# Flatten the $STRING and return the result.
-sub flatten ($)
+# $STRING
+# flatten ($ORIGINAL_STRING)
+# --------------------------
+sub flatten
 {
   $_ = shift;
 
@@ -6559,7 +6568,7 @@ sub flatten ($)
 # ---------------------------------------
 # Return the value associated to $KEY in %PAIRS, as used on $TOKEN
 # (which should be ?KEY? or any of the special %% requests)..
-sub transform_token ($$$)
+sub transform_token ($\%$)
 {
   my ($token, $transform, $key) = @_;
   my $res = $transform->{$key};
@@ -6574,7 +6583,7 @@ sub transform_token ($$$)
 #   - replaces %KEY% with $VAL,
 #   - enables/disables ?KEY? and ?!KEY?,
 #   - replaces %?KEY% with TRUE or FALSE.
-sub transform ($$)
+sub transform ($\%)
 {
   my ($token, $transform) = @_;
 
@@ -6583,18 +6592,18 @@ sub transform ($$)
   # when there is neither IFTRUE nor IFFALSE.
   if ($token =~ /^%([\w\-]+)%$/)
     {
-      return transform_token ($token, $transform, $1);
+      return transform_token ($token, %$transform, $1);
     }
   # %?KEY%.
   elsif ($token =~ /^%\?([\w\-]+)%$/)
     {
-      return transform_token ($token, $transform, $1) ? 'TRUE' : 'FALSE';
+      return transform_token ($token, %$transform, $1) ? 'TRUE' : 'FALSE';
     }
   # ?KEY? and ?!KEY?.
   elsif ($token =~ /^ \? (!?) ([\w\-]+) \? $/x)
     {
       my $neg = ($1 eq '!') ? 1 : 0;
-      my $val = transform_token ($token, $transform, $2);
+      my $val = transform_token ($token, %$transform, $2);
       return (!!$val == $neg) ? '##%' : '';
     }
   else
@@ -6609,7 +6618,7 @@ sub transform ($$)
 # Load a $MAKEFILE, apply the %TRANSFORM, and return the result.
 # No extra parsing or post-processing is done (i.e., recognition of
 # rules declaration or of make variables definitions).
-sub preprocess_file ($%)
+sub preprocess_file
 {
   my ($file, %transform) = @_;
 
@@ -6661,7 +6670,7 @@ sub preprocess_file ($%)
   # Substitute Automake template tokens.
   s/(?: % \?? [\w\-]+ %
       | \? !? [\w\-]+ \?
-    )/transform($&, \%transform)/gex;
+    )/transform($&, %transform)/gex;
   # transform() may have added some ##%-comments to strip.
   # (we use '##%' instead of '##' so we can distinguish ##%##%##% from
   # ####### and do not remove the latter.)
@@ -6676,7 +6685,7 @@ sub preprocess_file ($%)
 # -----------------------------------------
 # Load a $MAKEFILE, apply the %TRANSFORM, and return it as a list of
 # paragraphs.
-sub make_paragraphs ($%)
+sub make_paragraphs
 {
   my ($file, %transform) = @_;
   $transform{FIRST} = !$transformed_files{$file};
@@ -6723,7 +6732,7 @@ sub make_paragraphs ($%)
 # Return contents of a file from $libdir/am, automatically skipping
 # macros or rules which are already known. $IS_AM iff the caller is
 # reading an Automake file (as opposed to the user's Makefile.am).
-sub file_contents_internal ($$$%)
+sub file_contents_internal
 {
     my ($is_am, $file, $where, %transform) = @_;
 
@@ -6915,7 +6924,7 @@ sub file_contents_internal ($$$%)
 # -----------------------------------------------
 # Return contents of a file from $libdir/am, automatically skipping
 # macros or rules which are already known.
-sub file_contents ($$%)
+sub file_contents
 {
     my ($basename, $where, %transform) = @_;
     my ($comments, $variables, $rules) =
@@ -6941,7 +6950,7 @@ sub file_contents ($$%)
 # variable "zardir" is defined, then "zar_PROGRAMS" becomes valid.
 # This is to provide a little extra flexibility in those cases which
 # need it.
-sub am_primary_prefixes ($$@)
+sub am_primary_prefixes
 {
   my ($primary, $can_dist, @prefixes) = @_;
 
@@ -7018,7 +7027,7 @@ sub am_primary_prefixes ($$@)
 # FIXME: this should be rewritten to be cleaner.  It should be broken
 # up into multiple functions.
 #
-sub am_install_var (@)
+sub am_install_var
 {
   my (@args) = @_;
 
@@ -7224,7 +7233,9 @@ sub am_install_var (@)
 my %make_dirs = ();
 my $make_dirs_set = 0;
 
-sub is_make_dir ($)
+# is_make_dir ($DIRECTORY)
+# ------------------------
+sub is_make_dir
 {
     my ($dir) = @_;
     if (! $make_dirs_set)
@@ -7278,7 +7289,7 @@ sub locate_aux_dir ()
 # push_required_file ($DIR, $FILE, $FULLFILE)
 # -------------------------------------------
 # Push the given file onto DIST_COMMON.
-sub push_required_file ($$$)
+sub push_required_file
 {
   my ($dir, $file, $fullfile) = @_;
 
@@ -7365,7 +7376,7 @@ my %required_file_not_found = ();
 # required_file_check_or_copy ($WHERE, $DIRECTORY, $FILE)
 # -------------------------------------------------------
 # Verify that the file must exist in $DIRECTORY, or install it.
-sub required_file_check_or_copy ($$$)
+sub required_file_check_or_copy
 {
   my ($where, $dir, $file) = @_;
 
@@ -7477,7 +7488,7 @@ sub required_file_check_or_copy ($$$)
 # $MYSTRICT is the strictness level at which this file becomes required.
 # Worker threads may queue up the action to be serialized by the master,
 # if $QUEUE is true
-sub require_file_internal ($$$@)
+sub require_file_internal
 {
   my ($where, $mystrict, $dir, $queue, @files) = @_;
 
@@ -7502,7 +7513,7 @@ sub require_file_internal ($$$@)
 
 # require_file ($WHERE, $MYSTRICT, @FILES)
 # ----------------------------------------
-sub require_file ($$@)
+sub require_file
 {
     my ($where, $mystrict, @files) = @_;
     require_file_internal ($where, $mystrict, $relative_dir, 0, @files);
@@ -7510,7 +7521,7 @@ sub require_file ($$@)
 
 # require_file_with_macro ($COND, $MACRO, $MYSTRICT, @FILES)
 # ----------------------------------------------------------
-sub require_file_with_macro ($$$@)
+sub require_file_with_macro
 {
     my ($cond, $macro, $mystrict, @files) = @_;
     $macro = rvar ($macro) unless ref $macro;
@@ -7521,7 +7532,7 @@ sub require_file_with_macro ($$$@)
 # ---------------------------------------------------------------
 # Require an AC_LIBSOURCEd file.  If AC_CONFIG_LIBOBJ_DIR was called, it
 # must be in that directory.  Otherwise expect it in the current directory.
-sub require_libsource_with_macro ($$$@)
+sub require_libsource_with_macro
 {
     my ($cond, $macro, $mystrict, @files) = @_;
     $macro = rvar ($macro) unless ref $macro;
@@ -7537,9 +7548,9 @@ sub require_libsource_with_macro ($$$@)
 }
 
 # queue_required_file_check_or_copy ($QUEUE, $KEY, $DIR, $WHERE,
-#                                     $MYSTRICT, @FILES)
+#                                    $MYSTRICT, @FILES)
 # --------------------------------------------------------------
-sub queue_required_file_check_or_copy ($$$$@)
+sub queue_required_file_check_or_copy
 {
     my ($queue, $key, $dir, $where, $mystrict, @files) = @_;
     my @serial_loc;
@@ -7556,7 +7567,7 @@ sub queue_required_file_check_or_copy ($$$$@)
 
 # require_queued_file_check_or_copy ($QUEUE)
 # ------------------------------------------
-sub require_queued_file_check_or_copy ($)
+sub require_queued_file_check_or_copy
 {
     my ($queue) = @_;
     my $where;
@@ -7590,7 +7601,7 @@ sub require_queued_file_check_or_copy ($)
 # require_conf_file ($WHERE, $MYSTRICT, @FILES)
 # ---------------------------------------------
 # Looks in configuration path, as specified by AC_CONFIG_AUX_DIR.
-sub require_conf_file ($$@)
+sub require_conf_file
 {
     my ($where, $mystrict, @files) = @_;
     my $queue = defined $required_conf_file_queue ? 1 : 0;
@@ -7601,7 +7612,7 @@ sub require_conf_file ($$@)
 
 # require_conf_file_with_macro ($COND, $MACRO, $MYSTRICT, @FILES)
 # ---------------------------------------------------------------
-sub require_conf_file_with_macro ($$$@)
+sub require_conf_file_with_macro
 {
     my ($cond, $macro, $mystrict, @files) = @_;
     require_conf_file (rvar ($macro)->rdef ($cond)->location,
@@ -7617,7 +7628,7 @@ sub require_conf_file_with_macro ($$$@)
 # dependent upon.
 # We don't want to emit the rule twice, and want to reuse it
 # for directories with equivalent names (e.g., 'foo/bar' and './foo//bar').
-sub require_build_directory ($)
+sub require_build_directory
 {
   my $directory = shift;
 
@@ -7656,7 +7667,7 @@ sub require_build_directory ($)
 # If $FILE lies in a subdirectory, emit a rule to create this
 # directory and return the file that $FILE should be made
 # dependent upon.  Otherwise, just return the empty string.
-sub require_build_directory_maybe ($)
+sub require_build_directory_maybe
 {
     my $file = shift;
     my $directory = dirname ($file);
@@ -7674,7 +7685,7 @@ sub require_build_directory_maybe ($)
 ################################################################
 
 # Push a list of files onto '@dist_common'.
-sub push_dist_common (@)
+sub push_dist_common
 {
   prog_error "push_dist_common run after handle_dist"
     if $handle_dist_run;
@@ -7689,7 +7700,7 @@ sub push_dist_common (@)
 # ----------------------------------------------
 # Generate a Makefile.in given the name of the corresponding Makefile and
 # the name of the file output by config.status.
-sub generate_makefile ($$)
+sub generate_makefile
 {
   my ($makefile_am, $makefile_in) = @_;
 
@@ -7864,15 +7875,12 @@ sub generate_makefile ($$)
   print $gm_file $output;
 }
 
-################################################################
-
-
-
 
 ################################################################
 
+
 # Helper function for usage().
-sub print_autodist_files (@)
+sub print_autodist_files
 {
   # NOTE: we need to call our 'uniq' function with the leading '&'
   # here, because otherwise perl complains that "Unquoted string
@@ -8051,7 +8059,9 @@ sub parse_arguments ()
 }
 
 
-sub handle_makefile ($)
+# handle_makefile ($MAKEFILE)
+# ---------------------------
+sub handle_makefile
 {
   my ($file) =  @_;
   ($am_file = $file) =~ s/\.in$//;
@@ -8110,7 +8120,7 @@ sub get_number_of_threads ()
 #
 # The latter requires that the makefile that deals with the aux dir
 # files be handled last, done by the master thread.
-sub handle_makefiles_threaded ($)
+sub handle_makefiles_threaded
 {
   my ($nthreads) = @_;