[PATCH] {maint} cosmetics: fix some "docstring-like" comments in automake

[Stefano Lattarini]

* automake.in: Here.  And remove some redundant ones.

Signed-off-by: Stefano Lattarini <address@hidden>
---

 I intend to push this in a couple of days (to maint) if there is no objection.

 Regards,
   Stefano

 automake.in | 107 ++++++++++++------------------------------------------------
 1 file changed, 20 insertions(+), 87 deletions(-)

diff --git a/automake.in b/automake.in
index d4c25c4..1523053 100644
--- a/automake.in
+++ b/automake.in
@@ -1070,11 +1070,9 @@ sub define_verbose_var ($$;$)
       if (! vardef ($verbose_var, TRUE));
 }
 
-# Above should not be needed in the general automake code.
-
 # verbose_flag (NAME)
 # -------------------
-# Contents of %VERBOSE%: variable to expand before rule command.
+# Contents of '%VERBOSE%' variable to expand before rule command.
 sub verbose_flag ($)
 {
     my ($name) = @_;
@@ -1104,8 +1102,6 @@ sub define_verbose_tagvar ($)
     define_verbose_var ($name, '@echo "  '. $name . ' ' x (8 - length ($name)) 
. '" $@;');
 }
 
-# define_verbose_texinfo
-# ----------------------
 # Engage the needed silent rules machinery for assorted texinfo commands.
 sub define_verbose_texinfo ()
 {
@@ -1118,8 +1114,6 @@ sub define_verbose_texinfo ()
   define_verbose_var('texidevnull', '> /dev/null');
 }
 
-# define_verbose_libtool
-# ----------------------
 # Engage the needed silent rules machinery for 'libtool --silent'.
 sub define_verbose_libtool ()
 {
@@ -2302,7 +2296,7 @@ sub handle_ALLOCA ($$$)
   saw_extension ('.c');
 }
 
-# Canonicalize the input parameter
+# Canonicalize the input parameter.
 sub canonicalize ($)
 {
     my ($string) = @_;
@@ -2329,9 +2323,6 @@ sub check_canonical_spelling ($@)
   return $xname;
 }
 
-
-# handle_compile ()
-# -----------------
 # Set up the compile suite.
 sub handle_compile ()
 {
@@ -2386,8 +2377,6 @@ sub handle_compile ()
     $output_rules .= "$coms$rules";
 }
 
-# handle_libtool ()
-# -----------------
 # Handle libtool rules.
 sub handle_libtool ()
 {
@@ -2415,9 +2404,7 @@ sub handle_libtool ()
                                   LTRMS => join ("\n", @libtool_rms));
 }
 
-# handle_programs ()
-# ------------------
-# Handle C programs.
+
 sub handle_programs ()
 {
   my @proglist = am_install_var ('progs', 'PROGRAMS',
@@ -2507,9 +2494,6 @@ sub handle_programs ()
 }
 
 
-# handle_libraries ()
-# -------------------
-# Handle libraries.
 sub handle_libraries ()
 {
   my @liblist = am_install_var ('libs', 'LIBRARIES',
@@ -2620,9 +2604,6 @@ sub handle_libraries ()
 }
 
 
-# handle_ltlibraries ()
-# ---------------------
-# Handle shared libraries.
 sub handle_ltlibraries ()
 {
   my @liblist = am_install_var ('ltlib', 'LTLIBRARIES',
@@ -2892,7 +2873,6 @@ sub check_typos ()
 }
 
 
-# Handle scripts.
 sub handle_scripts ()
 {
     # NOTE we no longer automatically clean SCRIPTS, because it is
@@ -2904,8 +2884,6 @@ sub handle_scripts ()
 }
 
 
-
-
 ## ------------------------ ##
 ## Handling Texinfo files.  ##
 ## ------------------------ ##
@@ -3064,7 +3042,7 @@ sub output_texinfo_build_rules ($$$@)
 # ($MOSTLYCLEAN, $TEXICLEAN, $MAINTCLEAN)
 # handle_texinfo_helper ($info_texinfos)
 # --------------------------------------
-# Handle all Texinfo source; helper for handle_texinfo.
+# Handle all Texinfo source; helper for 'handle_texinfo'.
 sub handle_texinfo_helper ($)
 {
   my ($info_texinfos) = @_;
@@ -3384,9 +3362,6 @@ EOF
 }
 
 
-# handle_texinfo ()
-# -----------------
-# Handle all Texinfo source.
 sub handle_texinfo ()
 {
   reject_var 'TEXINFOS', "'TEXINFOS' is an anachronism; use 'info_TEXINFOS'";
@@ -3415,7 +3390,6 @@ sub handle_texinfo ()
 }
 
 
-# Handle any man pages.
 sub handle_man_pages ()
 {
   reject_var 'MANS', "'MANS' is an anachronism; use 'man_MANS'";
@@ -3554,7 +3528,7 @@ sub handle_man_pages ()
     unless option 'no-installman';
 }
 
-# Handle DATA variables.
+
 sub handle_data ()
 {
     am_install_var ('-noextra', '-candist', 'data', 'DATA',
@@ -3563,7 +3537,7 @@ sub handle_data ()
                     'pkgdata', 'lisp', 'noinst', 'check');
 }
 
-# Handle TAGS.
+
 sub handle_tags ()
 {
     my @config;
@@ -3631,8 +3605,6 @@ sub user_phony_rule ($)
 }
 
 
-# handle_dist
-# -----------
 # Handle 'dist' target.
 sub handle_dist ()
 {
@@ -3825,9 +3797,7 @@ sub check_directories_in_var ($)
      skip_ac_subst => 1);
 }
 
-# handle_subdirs ()
-# -----------------
-# Handle subdirectories.
+
 sub handle_subdirs ()
 {
   my $subdirs = var ('SUBDIRS');
@@ -3883,7 +3853,7 @@ sub scan_aclocal_m4 ()
 }
 
 
-# Helper function for substitute_ac_subst_variables.
+# Helper function for 'substitute_ac_subst_variables'.
 sub substitute_ac_subst_variables_worker($)
 {
   my ($token) = @_;
@@ -4290,7 +4260,6 @@ sub handle_configure ($$$@)
                          @actual_other_vpath_files);
 }
 
-# Handle C headers.
 sub handle_headers ()
 {
     my @r = am_install_var ('-defaultdist', 'header', 'HEADERS', 'include',
@@ -4359,7 +4328,7 @@ sub handle_gettext ()
   require_file ($ac_gettext_location, GNU, 'ABOUT-NLS');
 }
 
-# Handle footer elements.
+# Emit makefile footer.
 sub handle_footer ()
 {
     reject_rule ('.SUFFIXES',
@@ -4411,7 +4380,7 @@ sub handle_install ()
 }
 
 
-# Deal with all and all-am.
+# Deal with 'all' and 'all-am'.
 sub handle_all ($)
 {
     my ($makefile) = @_;
@@ -4472,7 +4441,7 @@ sub handle_all ($)
       }
 }
 
-# Generate helper targets for user recursion, where needed.
+# Generate helper targets for user-defined recursive targets, where needed.
 sub handle_user_recursion ()
 {
   return unless @extra_recursive_targets;
@@ -4499,8 +4468,6 @@ sub handle_user_recursion ()
 }
 
 
-# do_check_merge_target ()
-# ------------------------
 # Handle check merge target specially.
 sub do_check_merge_target ()
 {
@@ -4537,8 +4504,6 @@ sub do_check_merge_target ()
     if var ('BUILT_SOURCES');
 }
 
-# handle_clean ($MAKEFILE)
-# ------------------------
 # Handle all 'clean' targets.
 sub handle_clean ($)
 {
@@ -4608,8 +4573,6 @@ sub target_cmp
 }
 
 
-# handle_factored_dependencies ()
-# -------------------------------
 # Handle everything related to gathered targets.
 sub handle_factored_dependencies ()
 {
@@ -4696,8 +4659,6 @@ sub handle_factored_dependencies ()
 }
 
 
-# handle_tests_dejagnu ()
-# -----------------------
 sub handle_tests_dejagnu ()
 {
     push (@check_tests, 'check-DEJAGNU');
@@ -4767,7 +4728,7 @@ sub is_valid_test_extension ($)
   return 0;
 }
 
-# Handle TESTS variable and other checks.
+
 sub handle_tests ()
 {
   if (option 'dejagnu')
@@ -4901,7 +4862,6 @@ sub handle_tests ()
     }
 }
 
-# Handle Emacs Lisp.
 sub handle_emacs_lisp ()
 {
   my @elfiles = am_install_var ('-candist', 'lisp', 'LISP',
@@ -4922,7 +4882,6 @@ sub handle_emacs_lisp ()
                     'EMACS', 'lispdir');
 }
 
-# Handle Python
 sub handle_python ()
 {
   my @pyfiles = am_install_var ('-defaultdist', 'python', 'PYTHON',
@@ -4934,7 +4893,6 @@ sub handle_python ()
   define_variable ('py_compile', "$am_config_aux_dir/py-compile", INTERNAL);
 }
 
-# Handle Java.
 sub handle_java ()
 {
     my @sourcelist = am_install_var ('-candist',
@@ -4979,7 +4937,6 @@ sub handle_java ()
 }
 
 
-# Handle some of the minor options.
 sub handle_minor_options ()
 {
   if (option 'readme-alpha')
@@ -5085,8 +5042,6 @@ sub scan_autoconf_config_files ($$)
 }
 
 
-# scan_autoconf_traces ($FILENAME)
-# --------------------------------
 sub scan_autoconf_traces ($)
 {
   my ($filename) = @_;
@@ -5391,8 +5346,6 @@ EOF
 }
 
 
-# scan_autoconf_files ()
-# ----------------------
 # Check whether we use 'configure.ac' or 'configure.in'.
 # Scan it (and possibly 'aclocal.m4') for interesting things.
 # We must scan aclocal.m4 because there might be AC_SUBSTs and such there.
@@ -5924,9 +5877,7 @@ sub derive_suffix ($$)
 }
 
 
-################################################################
-
-# Pretty-print something and append to output_rules.
+# Pretty-print something and append to '$output_rules'.
 sub pretty_print_rule ($$@)
 {
     $output_rules .= makefile_wrap (shift, shift, @_);
@@ -6151,9 +6102,6 @@ sub define_compiler_variable ($)
 }
 
 
-# define_linker_variable ($LANG)
-# ------------------------------
-# Define linker variables.
 sub define_linker_variable ($)
 {
     my ($lang) = @_;
@@ -6533,8 +6481,6 @@ sub read_am_file ($$)
 }
 
 
-# define_standard_variables ()
-# ----------------------------
 # A helper for read_main_am_file which initializes configure variables
 # and variables from header-vars.am.
 sub define_standard_variables ()
@@ -6552,7 +6498,6 @@ sub define_standard_variables ()
   $output_vars .= $comments . $rules;
 }
 
-# Read main am file.
 sub read_main_am_file ($$)
 {
     my ($amfile, $infile) = @_;
@@ -6580,9 +6525,6 @@ sub read_main_am_file ($$)
 
 ################################################################
 
-# $FLATTENED
-# flatten ($STRING)
-# -----------------
 # Flatten the $STRING and return the result.
 sub flatten ($)
 {
@@ -6598,7 +6540,7 @@ sub flatten ($)
 
 
 # transform_token ($TOKEN, \%PAIRS, $KEY)
-# =======================================
+# ---------------------------------------
 # 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 ($$$)
@@ -6611,7 +6553,7 @@ sub transform_token ($$$)
 
 
 # transform ($TOKEN, \%PAIRS)
-# ===========================
+# ---------------------------
 # If ($TOKEN, $VAL) is in %PAIRS:
 #   - replaces %KEY% with $VAL,
 #   - enables/disables ?KEY? and ?!KEY?,
@@ -7043,6 +6985,9 @@ sub am_primary_prefixes ($$@)
 }
 
 
+# am_install_var (-OPTION..., file, HOW, where...)
+# ------------------------------------------------
+#
 # Handle 'where_HOW' variable magic.  Does all lookups, generates
 # install code, and possibly generates code to define the primary
 # variable.  The first argument is the name of the .am file to munge,
@@ -7057,7 +7002,6 @@ sub am_primary_prefixes ($$@)
 # FIXME: this should be rewritten to be cleaner.  It should be broken
 # up into multiple functions.
 #
-# Usage is: am_install_var (OPTION..., file, HOW, where...)
 sub am_install_var (@)
 {
   my (@args) = @_;
@@ -7316,7 +7260,7 @@ sub locate_aux_dir ()
 
 
 # push_required_file ($DIR, $FILE, $FULLFILE)
-# -------------------------------------------------
+# -------------------------------------------
 # Push the given file onto DIST_COMMON.
 sub push_required_file ($$$)
 {
@@ -7713,7 +7657,7 @@ sub require_build_directory_maybe ($)
 
 ################################################################
 
-# Push a list of files onto dist_common.
+# Push a list of files onto '@dist_common'.
 sub push_dist_common (@)
 {
   prog_error "push_dist_common run after handle_dist"
@@ -7958,7 +7902,6 @@ sub print_autodist_files (@)
 }
 
 
-# Print usage information.
 sub usage ()
 {
     print "Usage: $0 [OPTION]... [Makefile]...
@@ -8009,9 +7952,6 @@ General help using GNU software: 
<http://www.gnu.org/gethelp/>.
 }
 
 
-# version ()
-# ----------
-# Print version information
 sub version ()
 {
   print <<EOF;
@@ -8095,9 +8035,6 @@ sub parse_arguments ()
 }
 
 
-# handle_makefile ($MAKEFILE_IN)
-# ------------------------------
-# Deal with $MAKEFILE_IN.
 sub handle_makefile ($)
 {
   my ($file) =  @_;
@@ -8118,8 +8055,6 @@ sub handle_makefile ($)
     }
 }
 
-# handle_makefiles_serial ()
-# --------------------------
 # Deal with all makefiles, without threads.
 sub handle_makefiles_serial ()
 {
@@ -8129,8 +8064,6 @@ sub handle_makefiles_serial ()
     }
 }
 
-# get_number_of_threads ()
-# ------------------------
 # Logic for deciding how many worker threads to use.
 sub get_number_of_threads ()
 {
-- 
1.8.1.1.701.g02339dd