lucy-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mar...@apache.org
Subject svn commit: r806145 - in /lucene/lucy/trunk/boilerplater: lib/Boilerplater/DocuComment.pm lib/Boilerplater/Parser.pm t/050-docucomment.t
Date Thu, 20 Aug 2009 12:38:46 GMT
Author: marvin
Date: Thu Aug 20 12:38:46 2009
New Revision: 806145

URL: http://svn.apache.org/viewvc?rev=806145&view=rev
Log:
Commit LUCY-20, adding Boilerplater::DocuComment.

Added:
    lucene/lucy/trunk/boilerplater/lib/Boilerplater/DocuComment.pm   (with props)
    lucene/lucy/trunk/boilerplater/t/050-docucomment.t   (with props)
Modified:
    lucene/lucy/trunk/boilerplater/lib/Boilerplater/Parser.pm

Added: lucene/lucy/trunk/boilerplater/lib/Boilerplater/DocuComment.pm
URL: http://svn.apache.org/viewvc/lucene/lucy/trunk/boilerplater/lib/Boilerplater/DocuComment.pm?rev=806145&view=auto
==============================================================================
--- lucene/lucy/trunk/boilerplater/lib/Boilerplater/DocuComment.pm (added)
+++ lucene/lucy/trunk/boilerplater/lib/Boilerplater/DocuComment.pm Thu Aug 20 12:38:46 2009
@@ -0,0 +1,158 @@
+use strict;
+use warnings;
+
+package Boilerplater::DocuComment;
+use Carp;
+
+our %new_PARAMS = (
+    description => undef,
+    brief       => undef,
+    long        => undef,
+    param_names => undef,
+    param_docs  => undef,
+    retval      => undef,
+);
+
+sub _new {
+    my $either = shift;
+    verify_args( \%new_PARAMS, @_ );
+    return bless { \%new_PARAMS, @_ };
+}
+
+sub parse {
+    my ( $either, $text ) = @_;
+
+    my ( @param_names, @param_docs );
+    my $self = bless {
+        brief       => undef,
+        long        => undef,
+        param_names => \@param_names,
+        param_docs  => \@param_docs,
+        retval      => undef,
+        },
+        ref($either) || $either;
+
+    # Strip comment open, close, and left border.
+    $text =~ s/\A\s*\/\*\*\s+//;
+    $text =~ s/\s+\*\/\s*\Z//;
+    $text =~ s/^\s*\* ?//gm;
+
+    # Extract the brief description.
+    $text =~ /^(.+?\.)(\s+|\Z)/s
+        or confess("Can't find at least one descriptive sentence in '$text'");
+    $self->{brief} = $1;
+
+    # terminated by @, empty line, or string end.
+    my $terminator = qr/((?=\@)|\n\s*\n|\Z)/;
+
+    # Extract @param, @return directives.
+    while (
+        $text =~ s/^\s*
+        \@param\s+
+        (\w+)   # param name
+        \s+
+        (.*?)   # param description
+        \s*
+        $terminator
+      //xsm
+        )
+    {
+        push @param_names, $1;
+        push @param_docs,  $2;
+    }
+    if ( $text =~ s/^\s*\@return\s+(.*?)$terminator//sm ) {
+        $self->{retval} = $1;
+    }
+
+    $text =~ s/^\s*//;
+    $text =~ s/\s*$//;
+    $self->{description} = $text;
+
+    $text =~ s/^(.+?\.)(\s+|\Z)//s;    # zap brief
+    $text =~ s/^\s*//;
+    $self->{long} = $text;
+
+    return $self;
+}
+
+sub get_param_names { shift->{param_names} }
+sub get_param_docs  { shift->{param_docs} }
+sub get_retval      { shift->{retval} }
+sub get_brief       { shift->{brief} }
+sub get_long        { shift->{long} }
+sub get_description { shift->{description} }
+
+1;
+
+__END__
+
+__POD__
+
+=head1 NAME
+
+Boilerplater::DocuComment - Formatted comment a la Doxygen.
+
+=head1 SYNOPSIS
+
+    my $text = <<'END_COMMENT';
+    /** Brief description.
+     *
+     * Start the long description.  More long description.
+     * 
+     * @param foo A Foo.
+     * @param bar A Bar.
+     * @return a return value.
+     */
+    END_COMMENT
+    my $docucomment = Boilerplater::DocuComment->parse($text);
+
+=head1 CONSTRUCTORS 
+
+=head2 parse 
+
+    my $self = Boilerplater::DocuComment->parse($text);
+
+Parse comment text.
+
+=head2 new
+
+    my $self = Boilerplater::DocuComment->new(
+        description => "Brief.  Start long.  More long.",
+        brief       => "Brief.",
+        long        => "Long start. More long.",
+        param_names => \@param_names,
+        param_docs  => \@param_docs,
+        retval      => "a return value."
+    );
+
+=over
+
+=item * B<description> - The complete description. 
+
+=item * B<brief> - The first sentence of the description (a "brief"
+description).
+
+=item * B<long> - The description minus the first sentence.
+
+=item * B<param_names> - An array of param names.
+
+=item * B<param_docs> - An array containing a blurb for each param name.
+
+=item * B<retval> - Return value.
+
+=back
+
+=head1 METHODS
+
+=head2 get_description get_brief get_long get_param_names get_param_docs get_retval
+
+Accessors.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 2008-2009 Marvin Humphrey
+
+This program is free software; you can redistribute it and/or modify it under
+the same terms as Perl itself.
+
+=cut

Propchange: lucene/lucy/trunk/boilerplater/lib/Boilerplater/DocuComment.pm
------------------------------------------------------------------------------
    svn:eol-style = native

Modified: lucene/lucy/trunk/boilerplater/lib/Boilerplater/Parser.pm
URL: http://svn.apache.org/viewvc/lucene/lucy/trunk/boilerplater/lib/Boilerplater/Parser.pm?rev=806145&r1=806144&r2=806145&view=diff
==============================================================================
--- lucene/lucy/trunk/boilerplater/lib/Boilerplater/Parser.pm (original)
+++ lucene/lucy/trunk/boilerplater/lib/Boilerplater/Parser.pm Thu Aug 20 12:38:46 2009
@@ -15,6 +15,7 @@
 use Boilerplater::Type::Object;
 use Boilerplater::Type::Composite;
 use Boilerplater::Variable;
+use Boilerplater::DocuComment;
 use Carp;
 
 our $grammar = <<'END_GRAMMAR';
@@ -179,6 +180,10 @@
     ...!reserved_word /[a-zA-Z_]\w*/x
     { $item[2] }
 
+docucomment:
+    /\/\*\*.*?\*\//s
+    { Boilerplater::DocuComment->parse($item[1]) }
+
 constant_expression:
       /\d+/
     | /[A-Z_]+/

Added: lucene/lucy/trunk/boilerplater/t/050-docucomment.t
URL: http://svn.apache.org/viewvc/lucene/lucy/trunk/boilerplater/t/050-docucomment.t?rev=806145&view=auto
==============================================================================
--- lucene/lucy/trunk/boilerplater/t/050-docucomment.t (added)
+++ lucene/lucy/trunk/boilerplater/t/050-docucomment.t Thu Aug 20 12:38:46 2009
@@ -0,0 +1,43 @@
+use strict;
+use warnings;
+
+use Test::More tests => 10;
+
+BEGIN { use_ok('Boilerplater::DocuComment') }
+use Boilerplater::Parser;
+
+my $parser = Boilerplater::Parser->new;
+isa_ok( $parser->docucomment('/** foo. */'), "Boilerplater::DocuComment" );
+
+my $text = <<'END_COMMENT';
+/** 
+ * Brief description.  Long description. 
+ * 
+ * More long description.
+ * 
+ * @param foo A foo.
+ * @param bar A bar.
+ *
+ * @param baz A baz.
+ * @return a return value.
+ */
+END_COMMENT
+
+my $docucomment = Boilerplater::DocuComment->parse($text);
+
+like(
+    $docucomment->get_description,
+    qr/^Brief.*long description.\s*\Z/ims,
+    "get_description"
+);
+is( $docucomment->get_brief, "Brief description.", "brief" );
+like( $docucomment->get_long, qr/^Long.*long description.\s*\Z/ims, "long" );
+is_deeply( $docucomment->get_param_names, [qw( foo bar baz )],
+    "param names" );
+is( $docucomment->get_param_docs->[0], "A foo.", '@param terminated by @' );
+is( $docucomment->get_param_docs->[1],
+    "A bar.", '@param terminated by empty line' );
+is( $docucomment->get_param_docs->[2],
+    "A baz.", '@param terminated next element, @return' );
+is( $docucomment->get_retval, "a return value.", "get_retval" );
+

Propchange: lucene/lucy/trunk/boilerplater/t/050-docucomment.t
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message