generate_uudmap.c: add comments and headers

Add some comments at the top of this file to explain what it does.

Also make it add comment headers at the tops of the three files it
generates (uudmap.h bitcount.h mg_data.h) which explain that the file
is auto-generated and what its purpose is.

1 files changed, 54 insertions, 7 deletions

diff --git a/generate_uudmap.c b/generate_uudmap.c
index 4c7d56c6d4..5ab7d8197f 100644
--- a/generate_uudmap.c
+++ b/generate_uudmap.c
@@ -1,7 +1,38 @@
-/* Originally this program just generated uudmap.h
+/* generate_uudmap.c:
+
+   Create three .h files, whose names are specified as argv[1..3],
+   but are usually uudmap.h, bitcount.h and mg_data.h.
+
+   It uses mg_raw.h as input, plus it relies on the C compiler knowing
+   the ord value of character literals under EBCDIC, to generate output
+   tables on an order which are platform-specific.
+
+   The outputs are:
+
+     uudmap.h:
+         The values which will populate PL_uumap[], as used by
+         unpack('u').
+
+     bitcount.h
+          The values which will populate PL_bitcount[]:
+          this is a count of bits for each U8 value 0..255.
+          (I'm not sure why this has to be generated - surely it's
+          platform-independent - DAPM.)
+
+     mg_data.h
+          Takes the input from mg_raw.h and sorts by it magic char;
+          the values will populate PL_magic_data[]: this is an array of
+          per-magic U8 values containing an index into PL_magic_vtables[]
+          plus two flags:
+             PERL_MAGIC_READONLY_ACCEPTABLE
+             PERL_MAGIC_VALUE_MAGIC
+
+   Originally this program just generated uudmap.h
    However, when we later wanted to generate bitcount.h, it was easier to
    refactor it and keep the same name, than either alternative - rename it,
-   or duplicate all of the Makefile logic for a second program.  */
+   or duplicate all of the Makefile logic for a second program.
+   Ditto when mg_data.h was added.
+*/
 
 #include <stdio.h>
 #include <stdlib.h>
@@ -73,7 +104,9 @@ format_char_block(FILE *out, const void *thing, size_t count) {
 static void
 output_to_file(const char *progname, const char *filename,
 	       void (format_function)(FILE *out, const void *thing, size_t count),
-	       const void *thing, size_t count) {
+	       const void *thing, size_t count,
+               const char *header
+) {
   FILE *const out = fopen(filename, "w");
 
   if (!out) {
@@ -82,7 +115,10 @@ output_to_file(const char *progname, const char *filename,
     exit(1);
   }
 
-  fputs("{\n", out);
+  fprintf(out, "/* %s:\n", filename);
+  fprintf(out, " * THIS FILE IS AUTO-GENERATED DURING THE BUILD by: %s\n",
+                progname);
+  fprintf(out, " *\n%s\n*/\n{\n", header);
   format_function(out, thing, count);
   fputs("}\n", out);
 
@@ -123,7 +159,9 @@ int main(int argc, char **argv) {
   PL_uudmap[(U8)' '] = 0;
 
   output_to_file(argv[0], argv[1], &format_char_block,
-		 (const void *)PL_uudmap, sizeof(PL_uudmap));
+		 (const void *)PL_uudmap, sizeof(PL_uudmap),
+        " * These values will populate PL_uumap[], as used by unpack('u')"
+  );
 
   for (bits = 1; bits < 256; bits++) {
     if (bits & 1)	PL_bitcount[bits]++;
@@ -137,7 +175,10 @@ int main(int argc, char **argv) {
   }
 
   output_to_file(argv[0], argv[2], &format_char_block,
-		 (const void *)PL_bitcount, sizeof(PL_bitcount));
+		 (const void *)PL_bitcount, sizeof(PL_bitcount),
+     " * These values will populate PL_bitcount[]:\n"
+     " * this is a count of bits for each U8 value 0..255"
+  );
 
   while (p->value) {
       mg_data[p->type].value = p->value;
@@ -146,7 +187,13 @@ int main(int argc, char **argv) {
   }
       
   output_to_file(argv[0], argv[3], &format_mg_data,
-		 (const void *)mg_data, sizeof(mg_data)/sizeof(mg_data[0]));
+		 (const void *)mg_data, sizeof(mg_data)/sizeof(mg_data[0]),
+     " * These values will populate PL_magic_data[]: this is an array of\n"
+     " * per-magic U8 values containing an index into PL_magic_vtables[]\n"
+     " * plus two flags:\n"
+     " *    PERL_MAGIC_READONLY_ACCEPTABLE\n"
+     " *    PERL_MAGIC_VALUE_MAGIC"
+  );
 
   return 0;
 }