Skip to content
Browse files

Add more function-level documentation in POD format. Reposition some …

…existing POD.
  • Loading branch information...
1 parent e69972a commit 114e8c674a4c1aea5194c7c6e0f48fae388464b7 @jkeenan jkeenan committed Jun 12, 2012
Showing with 137 additions and 36 deletions.
  1. +137 −36 lib/Parrot/Vtable.pm
View
173 lib/Parrot/Vtable.pm
@@ -1,4 +1,15 @@
-# Copyright (C) 2001-2011, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
+package Parrot::Vtable;
+use strict;
+use base qw( Exporter );
+use FileHandle;
+our @EXPORT = qw(
+ parse_vtable
+ vtbl_defs
+ vtbl_struct
+ vtbl_macros
+ vtbl_embed
+);
=head1 NAME
@@ -14,25 +25,8 @@ C<Parrot::Vtable> provides a collection of functions for manipulating PMC
vtables. It is used by F<tools/build/pmc2c.pl>, F<tools/build/vtable_h.pl>,
F<tools/build/vtable_extend.pl> and F<tools/dev/gen_class.pl>.
-=head2 Functions
-
-The following functions are exported:
-
-=over 4
-
=cut
-package Parrot::Vtable;
-
-use strict;
-use warnings;
-
-use base qw( Exporter );
-
-use FileHandle;
-
-our @EXPORT = qw(parse_vtable vtbl_defs vtbl_struct vtbl_macros vtbl_embed);
-
sub make_re {
my $re = shift;
my $comp_re = qr/$re/;
@@ -61,15 +55,44 @@ sub parse_attrs {
return $result;
}
-=item C<parse_vtable($file)>
+=head1 FUNCTIONS
+
+The following functions are exported:
-Returns a reference to an array containing
+=head2 C<parse_vtable<()>
+
+=over 4
- [ return_type method_name parameters section MMD_type attributes ]
+=item * Purpose
+
+Parse vtable.
+
+=item * Arguments
+
+String holding path to vtable file.
+
+=item * Return Value
+
+Reference to an array containing:
+
+ [
+ return_type
+ method_name
+ parameters
+ section
+ MMD_type
+ attributes
+ ]
for each vtable function defined in C<$file>. If it is not an MMD method,
C<MMD_type> is -1.
+=item * Comment
+
+Used in C<Parrot::Pmc2c::VTable::build()>.
+
+=back
+
=cut
sub parse_vtable {
@@ -119,10 +142,32 @@ sub parse_vtable {
return [ @{$mmd}, sort { $a->[1] cmp $b->[1] } @{$vtable} ];
}
-=item C<vtbl_defs($vtable)>
+# all encapsulated below here
-Returns the C C<typedef> definitions for the elements in the referenced
-vtable array.
+=head2 C<vtbl_defs()>
+
+=over 4
+
+=item * Purpose
+
+Compose the C C<typedef> definitions for the elements in the referenced vtable
+array.
+
+=item * Arguments
+
+Reference to an array. This array ref is the output of this package's
+C<parse_vtable> method.
+
+=item * Return Value
+
+Returns string holding the C C<typedef> definitions for the elements in the
+referenced vtable array.
+
+Used in F<tools/build/vtable_h.pl>.
+
+=item * Comment
+
+=back
=cut
@@ -151,10 +196,30 @@ sub vtbl_defs {
return $defs;
}
-=item C<vtbl_struct($vtable)>
+=head2 C<vtbl_struct()>
-Returns the C C<struct> definitions for the elements in the referenced
-vtable array.
+=over 4
+
+=item * Purpose
+
+Compose the C C<struct> definitions for the elements in the referenced vtable
+array.
+
+=item * Arguments
+
+Reference to an array. This array ref is the output of this package's
+C<parse_vtable> method.
+
+=item * Return Value
+
+Returns a string holding the C C<struct> definitions for the elements in the
+referenced vtable array.
+
+Used in F<tools/build/vtable_h.pl>.
+
+=item * Comment
+
+=back
=cut
@@ -206,11 +271,31 @@ EOF
return $struct;
}
-=item C<vtbl_macros($vtable)>
+=head2 C<vtbl_macros()>
+
+=over 4
+
+=item * Purpose
-Returns the C C<#define> definitions for the elements in the referenced
+Compose the C C<#define> definitions for the elements in the referenced vtable
+array.
+
+=item * Arguments
+
+Reference to an array. This array ref is the output of this package's
+C<parse_vtable> method.
+
+=item * Return Value
+
+String holding the C C<#define> definitions for the elements in the referenced
vtable array.
+Used in F<tools/build/vtable_h.pl>.
+
+=item * Comment
+
+=back
+
=cut
sub vtbl_macros {
@@ -288,10 +373,26 @@ EOM
$macros;
}
-=item C<vtbl_embed($vtable)>
+=head2 C<vtbl_embed()>
+
+=over 4
+
+=item * Purpose
+
+=item * Arguments
+
+Reference to an array. This array ref is the output of this package's
+C<parse_vtable> method.
+
+=item * Return Value
+
+List of two strings holding the C function definitions to call the vtable functions on a PMC for the elements in the referenced vtable array.
+
+Used in F<tools/build/vtable_extend.pl>.
-Returns the C function definitions to call the vtable functions on a PMC for the
-elements in the referenced vtable array.
+=item * Comment
+
+=back
=cut
@@ -391,20 +492,20 @@ sub parse_params {
return @params;
}
-=back
-
=head1 SEE ALSO
=over 4
=item F<tools/build/vtable_extend.pl>
-=item F<tools/build/pmc2c.pl>
-
=item F<tools/build/vtable_h.pl>
+=item F<tools/build/pmc2c.pl>
+
=item F<tools/dev/gen_class.pl>
+=back
+
=cut
1;

0 comments on commit 114e8c6

Please sign in to comment.
Something went wrong with that request. Please try again.