Tue Aug 10 01:54:13 UTC 2010

Author: jkeenan
Date: Tue Aug 10 01:54:12 2010
New Revision: 48375
URL: https://trac.parrot.org/parrot/changeset/48375

Log:
[codingstd] Merge tt1726_pmc_pod branch into trunk.  Adds new file t/codingstd/pmc_docs.t to flag functions lacking documentation in .pmc files.

Added:
   trunk/t/codingstd/pmc_docs.t
      - copied unchanged from r48374, branches/tt1726_pmc_pod/t/codingstd/pmc_docs.t
Modified:
   trunk/   (props changed)
   trunk/MANIFEST
   trunk/compilers/data_json/Rules.mak   (props changed)
   trunk/compilers/imcc/Rules.in   (props changed)
   trunk/compilers/pct/Rules.mak   (props changed)
   trunk/compilers/pge/Rules.mak   (props changed)
   trunk/compilers/tge/Rules.mak   (props changed)
   trunk/config/auto/sizes/intval_maxmin_c.in   (props changed)
   trunk/config/auto/zlib/   (props changed)
   trunk/docs/book/draft/README   (props changed)
   trunk/docs/book/draft/appa_glossary.pod   (props changed)
   trunk/docs/book/draft/appb_patch_submission.pod   (props changed)
   trunk/docs/book/draft/appc_command_line_options.pod   (props changed)
   trunk/docs/book/draft/appd_build_options.pod   (props changed)
   trunk/docs/book/draft/appe_source_code.pod   (props changed)
   trunk/docs/book/draft/ch01_introduction.pod   (props changed)
   trunk/docs/book/draft/ch02_getting_started.pod   (props changed)
   trunk/docs/book/draft/ch07_dynpmcs.pod   (props changed)
   trunk/docs/book/draft/ch08_dynops.pod   (props changed)
   trunk/docs/book/draft/ch10_opcode_reference.pod   (props changed)
   trunk/docs/book/draft/ch11_directive_reference.pod   (props changed)
   trunk/docs/book/draft/ch12_operator_reference.pod   (props changed)
   trunk/docs/book/draft/chXX_hlls.pod   (props changed)
   trunk/docs/book/draft/chXX_library.pod   (props changed)
   trunk/docs/book/draft/chXX_testing_and_debugging.pod   (props changed)
   trunk/docs/book/pct/ch01_introduction.pod   (props changed)
   trunk/docs/book/pct/ch02_getting_started.pod   (props changed)
   trunk/docs/book/pct/ch03_compiler_tools.pod   (props changed)
   trunk/docs/book/pct/ch04_pge.pod   (props changed)
   trunk/docs/book/pct/ch05_nqp.pod   (props changed)
   trunk/docs/dev/c_functions.pod   (props changed)
   trunk/docs/pdds/pdd30_install.pod   (props changed)
   trunk/examples/embed/cotorra.c   (props changed)
   trunk/examples/languages/abc/   (props changed)
   trunk/examples/languages/squaak/   (props changed)
   trunk/examples/pge/demo.pir   (props changed)
   trunk/ext/nqp-rx/Rules.mak   (props changed)
   trunk/include/parrot/call.h   (props changed)
   trunk/include/parrot/gc_api.h   (props changed)
   trunk/include/parrot/runcore_api.h   (props changed)
   trunk/include/parrot/runcore_profiling.h   (props changed)
   trunk/include/parrot/runcore_trace.h   (props changed)
   trunk/lib/Parrot/Configure/Step/Test.pm   (props changed)
   trunk/lib/Parrot/H2inc.pm   (props changed)
   trunk/ports/cygwin/parrot-1.0.0-1.cygport   (props changed)
   trunk/ports/debian/libparrot-dev.install.in   (props changed)
   trunk/ports/debian/libparrot.install.in   (props changed)
   trunk/ports/debian/parrot-doc.install.in   (props changed)
   trunk/ports/debian/parrot.install.in   (props changed)
   trunk/runtime/parrot/languages/   (props changed)
   trunk/runtime/parrot/library/Math/Rand.pir   (props changed)
   trunk/runtime/parrot/library/Rules.mak   (props changed)
   trunk/src/call/ops.c   (props changed)
   trunk/src/call/pcc.c   (props changed)
   trunk/src/gc/alloc_memory.c   (props changed)
   trunk/src/gc/alloc_resources.c   (props changed)
   trunk/src/gc/api.c   (props changed)
   trunk/src/gc/malloc.c   (props changed)
   trunk/src/gc/malloc_trace.c   (props changed)
   trunk/src/gc/mark_sweep.c   (props changed)
   trunk/src/gc/system.c   (props changed)
   trunk/src/interp/inter_cb.c   (props changed)
   trunk/src/interp/inter_create.c   (props changed)
   trunk/src/interp/inter_misc.c   (props changed)
   trunk/src/runcore/cores.c   (props changed)
   trunk/src/runcore/main.c   (props changed)
   trunk/src/runcore/profiling.c   (props changed)
   trunk/src/runcore/trace.c   (props changed)
   trunk/t/compilers/tge/NoneGrammar.tg   (props changed)
   trunk/t/oo/objects.t   (props changed)
   trunk/t/oo/root_new.t   (props changed)
   trunk/t/pmc/namespace-old.t   (props changed)
   trunk/t/src/embed.t   (props changed)
   trunk/t/steps/init/hints/linux-01.t   (props changed)
   trunk/tools/build/h2inc.pl   (props changed)
   trunk/tools/dev/fetch_languages.pl   (props changed)
   trunk/tools/dev/mk_gitignore.pl   (props changed)
   trunk/tools/util/perlcritic-cage.conf   (props changed)

Modified: trunk/MANIFEST
==============================================================================

--- trunk/MANIFEST	Tue Aug 10 01:10:47 2010	(r48374)
+++ trunk/MANIFEST	Tue Aug 10 01:54:12 2010	(r48375)
@@ -1,7 +1,7 @@
 # ex: set ro:
 # $Id$
 #
-# generated by tools/dev/mk_manifest_and_skip.pl Tue Aug  3 18:21:50 2010 UT
+# generated by tools/dev/mk_manifest_and_skip.pl Sun Aug  8 16:31:42 2010 UT
 #
 # See below for documentation on the format of this file.
 #
@@ -1503,6 +1503,7 @@
 t/codingstd/pdd_format.t                                    [test]
 t/codingstd/perlcritic.t                                    [test]
 t/codingstd/pir_code_coda.t                                 [test]
+t/codingstd/pmc_docs.t                                      [test]
 t/codingstd/pod_description.t                               [test]
 t/codingstd/pod_syntax.t                                    [test]
 t/codingstd/pod_todo.t                                      [test]

Copied: trunk/t/codingstd/pmc_docs.t (from r48374, branches/tt1726_pmc_pod/t/codingstd/pmc_docs.t)
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ trunk/t/codingstd/pmc_docs.t	Tue Aug 10 01:54:12 2010	(r48375, copy of r48374, branches/tt1726_pmc_pod/t/codingstd/pmc_docs.t)
@@ -0,0 +1,153 @@
+#! perl
+# Copyright (C) 2006-2010, Parrot Foundation.
+# $Id$
+
+use strict;
+use warnings;
+
+use lib qw( . lib ../lib ../../lib );
+use Test::More;
+use Parrot::Config qw(%PConfig);
+use Parrot::Distribution;
+use Parrot::Headerizer;
+
+=head1 NAME
+
+t/codingstd/pmc_docs.t - checks for missing function documentation
+
+=head1 SYNOPSIS
+
+    # test all files
+    % prove t/codingstd/pmc_docs.t
+
+    # test specific files
+    % perl t/codingstd/pmc_docs.t src/foo.pmc src/bar.pmc
+
+=head1 DESCRIPTION
+
+Checks that all PMC source files have documentation for each function
+declared.
+
+=cut
+
+my $DIST = Parrot::Distribution->new;
+my $headerizer = Parrot::Headerizer->new;
+
+my @files = @ARGV ? @ARGV :
+    map {s/^$PConfig{build_dir}\///; $_}
+    map {s/\\/\//g; $_}
+    map {$_->path} $DIST->pmc_source_files();
+
+plan tests => scalar @files;
+
+my %todos;
+while (<DATA>) {
+    next if /^#/;
+    next if /^\s*$/;
+    chomp;
+    $todos{$_} = 1;
+}
+
+my %all_files = ();
+
+# Traverse each file, analyzing each function declaration therein, then
+# post results in %all_files.
+
+foreach my $path (@files) {
+    my $buf = $DIST->slurp($path);
+    my @function_decls = $headerizer->extract_function_declarations($buf);
+
+    # We start out asserting that every file will have documentation for each
+    # of its function declarations.  We then seek to contradict this
+    # assertion.
+
+    my %this_file = ( overall => 1 );
+
+    for my $function_decl (@function_decls) {
+        my $escaped_decl
+            = $headerizer->generate_documentation_signature($function_decl);
+        $this_file{$function_decl}{esc} = $escaped_decl;
+
+        if ( $buf =~ m/^\Q$escaped_decl\E$(.*?)^=cut/sm ) {
+            my $docs = $1;
+            $docs =~ s/\s//g;
+            if ($docs eq '') { # boilerplate only
+                $this_file{$function_decl}{status} = 0;
+                $this_file{overall} = 0;
+            }
+            else { # documentation found
+                $this_file{$function_decl}{status} = 1;
+            }
+        }
+        else { # no documentation found
+            $this_file{$function_decl}{status} = undef;
+            $this_file{overall} = 0;
+        }
+    }
+    $all_files{$path} = \%this_file;
+}
+
+foreach my $path (sort keys %all_files) {
+    TODO: {
+        local $TODO = 'Missing function docs' if $todos{$path};
+        ok( $all_files{$path}{overall}, $path )
+            or diag( diagnosis( \%all_files, $path ) );
+    }
+}
+
+sub diagnosis {
+    my ($all_files_ref, $path) = @_;
+    my $missing = '';
+    my $boilerplate = '';
+    my %this_file = %{ $all_files_ref->{$path} };
+    delete $this_file{overall};
+    foreach my $decl ( sort keys %this_file ) {
+        if ( ! defined $this_file{$decl}{status} ) {
+            $missing .= "$decl\n";
+            $missing .= "Need:\n";
+            $missing .= "$this_file{$decl}{esc}\n\n";
+        }
+        elsif ( ! $this_file{$decl}{status} ) {
+            $boilerplate .= "$this_file{$decl}{esc}\n\n";
+        }
+        else {
+            # docs!
+        }
+    }
+    my $diagnosis = "$path\n";
+    $diagnosis .= "Undocumented functions:\n\n$missing" if $missing;
+    $diagnosis .= "Boilerplate only:\n$boilerplate" if $boilerplate;
+    return "$diagnosis";
+}
+
+__DATA__
+src/dynpmc/rational.pmc
+src/pmc/bigint.pmc
+src/pmc/bignum.pmc
+src/pmc/callcontext.pmc
+src/pmc/class.pmc
+src/pmc/complex.pmc
+src/pmc/coroutine.pmc
+src/pmc/eval.pmc
+src/pmc/fixedintegerarray.pmc
+src/pmc/hashiterator.pmc
+src/pmc/imageio.pmc
+src/pmc/imageiosize.pmc
+src/pmc/integer.pmc
+src/pmc/namespace.pmc
+src/pmc/nci.pmc
+src/pmc/null.pmc
+src/pmc/object.pmc
+src/pmc/orderedhash.pmc
+src/pmc/packfile.pmc
+src/pmc/role.pmc
+src/pmc/sub.pmc
+src/pmc/threadinterpreter.pmc
+src/pmc/unmanagedstruct.pmc
+
+# Local Variables:
+#   mode: cperl
+#   cperl-indent-level: 4
+#   fill-column: 100
+# End:
+# vim: expandtab shiftwidth=4:
