[svn:parrot] r48588 - trunk/tools/build

[jkeenan at svn.parrot.org]

Author: jkeenan
Date: Sat Aug 21 20:45:11 2010
New Revision: 48588
URL: https://trac.parrot.org/parrot/changeset/48588

Log:
Simplify documentation per http://trac.parrot.org/parrot/ticket/1725.

Modified:
   trunk/tools/build/headerizer.pl

Modified: trunk/tools/build/headerizer.pl
==============================================================================
--- trunk/tools/build/headerizer.pl	Fri Aug 20 18:38:47 2010	(r48587)
+++ trunk/tools/build/headerizer.pl	Sat Aug 21 20:45:11 2010	(r48588)
@@ -9,46 +9,51 @@
 
 =head1 SYNOPSIS
 
-    % perl tools/build/headerizer.pl OBJFILES
+  $ perl tools/build/headerizer.pl [object files]
 
-=head1 DESCRIPTION
+Generates C function declarations based on the function definitions in
+the C source code.
 
-Update the headers in F<include/parrot> with the function declarations in
-the F<*.pmc> or F<*.c> files that correspond to the F<*.o> files passed
-on the command line.
+=head1 DESCRIPTION
 
-=head1 TODO
+The headerizer works off of directives in the source and header files.
 
-* Generate docs from funcs
+One source file's public declarations can only go into one header file.
+However, one header file can have declarations from multiple source files.
+In other words, headers-to-source is one-to-many.
 
-* Somehow handle static functions in the source file
+=over 4
 
-=head1 NOTES
+=item C<HEADERIZER BEGIN:> F<source-filename> / C<HEADERIZER END:> F<source-filename>
 
-* the .c files MUST have a /* HEADERIZER HFILE: foo/bar.h */ directive in them
+Marks the beginning and end of a block of declarations in a header file.
 
-* Support for multiple .c files pointing at the same .h file
+    # In file foo.h
+    /* HEADERIZER BEGIN: src/foo.c */
+    /* HEADERIZER END: src/foo.c */
 
-* Does NOT remove all blocks in the .h file, so if a .c file
-disappears, its block is "orphaned" and will remain there.
+    /* HEADERIZER BEGIN: src/bar.c */
+    /* HEADERIZER END: src/bar.c */
 
-=head1 COMMAND-LINE OPTIONS
+=item C<HEADERIZER HFILE:> F<header-filename>
 
-=over 4
+Tells the headerizer where the declarations for the functions should go
 
-=item C<--macro=X>
+    # In file foo.c
+    /* HEADERIZER HFILE: foo.h */
 
-Print a list of all functions that have macro X.  For example, --macro=PARROT_EXPORT.
+    # In file bar.c
+    /* HEADERIZER HFILE: foo.h */
 
 =back
 
-=head1 COMMAND-LINE ARGUMENTS
+=head1 COMMAND-LINE OPTIONS
 
 =over 4
 
-=item C<OBJFILES>
+=item C<--macro=X>
 
-One or more object file names.
+Print a list of all functions that have macro X.  For example, --macro=PARROT_EXPORT.
 
 =back
 
@@ -443,51 +448,13 @@
     return;
 }
 
-=head1 NAME
-
-headerizer.pl
-
-=head1 SYNOPSIS
-
-  $ tools/build/headerizer.pl [object files]
-
-Generates C function declarations based on the function definitions in
-the C source code.
-
-=head1 DIRECTIVES
-
-The headerizer works off of directives in the source and header files.
-
-One source file's public declarations can only go into one header file.
-However, one header file can have declarations from multiple source files.
-In other words, headers-to-source is one-to-many.
-
-=over 4
-
-=item HEADERIZER BEGIN: F<source-filename> / HEADERIZER END: F<source-filename>
-
-Marks the beginning and end of a block of declarations in a header file.
-
-    # In file foo.h
-    /* HEADERIZER BEGIN: src/foo.c */
-    /* HEADERIZER END: src/foo.c */
-
-    /* HEADERIZER BEGIN: src/bar.c */
-    /* HEADERIZER END: src/bar.c */
-
-=item HEADERIZER HFILE: F<header-filename>
-
-Tells the headerizer where the declarations for the functions should go
-
-    # In file foo.c
-    /* HEADERIZER HFILE: foo.h */
-
-    # In file bar.c
-    /* HEADERIZER HFILE: foo.h */
-
-=back
-
-=cut
+# From earlier documentation:
+# * Generate docs from funcs
+# * Somehow handle static functions in the source file
+# * the .c files MUST have a /* HEADERIZER HFILE: foo/bar.h */ directive in them
+# * Support for multiple .c files pointing at the same .h file
+# * Does NOT remove all blocks in the .h file, so if a .c file
+#   disappears, its block is "orphaned" and will remain there.
 
 # Local Variables:
 #   mode: cperl