[svn:parrot] r37850 - in trunk: lib/Parrot t/codingstd tools/build

[coke at svn.parrot.org]

Author: coke
Date: Wed Apr  1 19:31:38 2009
New Revision: 37850
URL: https://trac.parrot.org/parrot/changeset/37850

Log:
[t/docs] have 'make headerizer' fix function signatures to match codingstd.

factor out logic from c_function_docs.t to a common method, replace logic
in headerizer that stripped off args to use this instead.

Modified:
   trunk/lib/Parrot/Headerizer.pm
   trunk/t/codingstd/c_function_docs.t
   trunk/tools/build/headerizer.pl

Modified: trunk/lib/Parrot/Headerizer.pm
==============================================================================
--- trunk/lib/Parrot/Headerizer.pm	Wed Apr  1 18:42:45 2009	(r37849)
+++ trunk/lib/Parrot/Headerizer.pm	Wed Apr  1 19:31:38 2009	(r37850)
@@ -221,6 +221,62 @@
     };
 }
 
+=item C<generate_documentation_signature>
+
+Given an extracted function signature, return a modified
+version suitable for inclusion in POD documentation.
+
+=cut
+
+sub generate_documentation_signature {
+    my $self = shift;
+    my $function_decl = shift;
+
+    $function_decl =~ s/\s+/ /g;
+
+    # strip out any PARROT_* prefixes
+    $function_decl =~ s/^\s*PARROT_[A-Z_]*\b\s+//gm;
+
+    # strip out any ARG* modifiers
+    $function_decl =~ s/ARG(?:IN|IN_NULLOK|OUT|OUT_NULLOK|MOD|MOD_NULLOK|FREE)\((.*?)\)/$1/g;
+
+    # strip out the SHIM modifier
+    $function_decl =~ s/SHIM\((.*?)\)/$1/g;
+
+    # strip out the NULL modifiers
+    $function_decl =~ s/(?:NULLOK|NOTNULL)\((.*?)\)/$1/g;
+
+    # SHIM_INTERP is still a PARROT_INTERP
+    $function_decl =~ s/SHIM_INTERP/PARROT_INTERP/g;
+
+    # wrap with POD
+    $function_decl = "=item C<$function_decl>";
+
+    # Wrap long lines.
+    my $line_len = 80;
+    return $function_decl if length($function_decl)<= $line_len;
+
+    my @doc_chunks = split /\s+/, $function_decl;
+    my $split_decl = '';
+    my @line;
+    while (@doc_chunks) {
+        my $chunk = shift @doc_chunks;
+        if (length(join(' ', @line, $chunk)) <= $line_len) {
+            push @line, $chunk;
+        } else {
+            $split_decl .= join(' ', @line) . "\n";
+            @line=($chunk);
+        }
+    }
+    if (@line) {
+        $split_decl .= join(' ', @line) . "\n";
+    }
+    
+    $split_decl =~ s/\n$//;
+
+    return $split_decl;
+}
+
 =item C<squawk($file, $func, $error)>
 
 Headerizer-specific ways of complaining if something went wrong.

Modified: trunk/t/codingstd/c_function_docs.t
==============================================================================
--- trunk/t/codingstd/c_function_docs.t	Wed Apr  1 18:42:45 2009	(r37849)
+++ trunk/t/codingstd/c_function_docs.t	Wed Apr  1 19:31:38 2009	(r37850)
@@ -56,35 +56,9 @@
 
     for my $function_decl (@function_decls) {
 
-        # strip out any PARROT_* prefixes
-        $function_decl =~ s/^\s*PARROT_[A-Z_]*\b\s+//gm;
+        my $escaped_decl = $headerizer->generate_documentation_signature($function_decl);
 
-        # strip out any ARG* modifiers
-        $function_decl =~ s/ARG(?:IN|IN_NULLOK|OUT|OUT_NULLOK|MOD|MOD_NULLOK|FREE)\((.*?)\)/$1/g;
-
-        # strip out the SHIM modifier
-        $function_decl =~ s/SHIM\((.*?)\)/$1/g;
-
-        # strip out the NULL modifiers
-        $function_decl =~ s/(?:NULLOK|NOTNULL)\((.*?)\)/$1/g;
-
-        # SHIM_INTERP is still a PARROT_INTERP
-        $function_decl =~ s/SHIM_INTERP/PARROT_INTERP/g;
-
-        my $escaped_decl = $function_decl;
-
-        # escape [, ], (, ), and *
-        $escaped_decl =~ s/\[/\\[/g;
-        $escaped_decl =~ s/\]/\\]/g;
-        $escaped_decl =~ s/\(/\\(/g;
-        $escaped_decl =~ s/\)/\\)/g;
-        $escaped_decl =~ s/\*/\\*/g;
-
-        # don't worry if the function declaration has embedded newlines in
-        # it and the documented function doesn't.
-        $escaped_decl =~ s/\s+/\\s+/g;
-
-        my $decl_rx = qr/^=item C<$escaped_decl>(.*?)^=cut/sm;
+        my $decl_rx = qr/^\Q$escaped_decl\E$(.*?)^=cut/sm;
 
         my $missing = '';
         if ( $buf =~ m/$decl_rx/) {

Modified: trunk/tools/build/headerizer.pl
==============================================================================
--- trunk/tools/build/headerizer.pl	Wed Apr  1 18:42:45 2009	(r37849)
+++ trunk/tools/build/headerizer.pl	Wed Apr  1 19:31:38 2009	(r37850)
@@ -6,6 +6,7 @@
 use warnings;
 use Carp qw( confess );
 
+
 =head1 NAME
 
 tools/build/headerizer.pl - Generates the function header parts of .h
@@ -61,6 +62,9 @@
 use Getopt::Long;
 use lib qw( lib );
 use Parrot::Config;
+use Parrot::Headerizer;
+
+my $headerizer = Parrot::Headerizer->new;
 
 my %warnings;
 my %opt;
@@ -163,11 +167,10 @@
     for my $decl ( @func_declarations ) {
         my $specs = function_components_from_declaration( $cfile_name, $decl );
         my $name = $specs->{name};
-        my $return_type = $specs->{return_type};
-        my $heading = "$return_type $name";
-        $heading = "static $heading" if $specs->{is_static};
 
-        $text =~ s/=item C<[^>]*\b$name\b[^>]*>\n/=item C<$heading>\n/sm or
+        my $heading = $headerizer->generate_documentation_signature($decl);
+
+        $text =~ s/=item C<[^>]*\b$name\b[^>]*>\n+/$heading\n\n/sm or
             warn "$name has no POD\n";
     }
     open( my $fhout, '>', $cfile_name ) or die "Can't create $cfile_name: $!";