Skip to content
This repository
Browse code

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

…existing POD.
  • Loading branch information...
commit 114e8c674a4c1aea5194c7c6e0f48fae388464b7 1 parent e69972a
James E Keenan jkeenan authored

Showing 1 changed file with 137 additions and 36 deletions. Show diff stats Hide diff stats

  1. +137 36 lib/Parrot/Vtable.pm
173 lib/Parrot/Vtable.pm
... ... @@ -1,4 +1,15 @@
1   -# Copyright (C) 2001-2011, Parrot Foundation.
  1 +# Copyright (C) 2001-2012, Parrot Foundation.
  2 +package Parrot::Vtable;
  3 +use strict;
  4 +use base qw( Exporter );
  5 +use FileHandle;
  6 +our @EXPORT = qw(
  7 + parse_vtable
  8 + vtbl_defs
  9 + vtbl_struct
  10 + vtbl_macros
  11 + vtbl_embed
  12 +);
2 13
3 14 =head1 NAME
4 15
@@ -14,25 +25,8 @@ C<Parrot::Vtable> provides a collection of functions for manipulating PMC
14 25 vtables. It is used by F<tools/build/pmc2c.pl>, F<tools/build/vtable_h.pl>,
15 26 F<tools/build/vtable_extend.pl> and F<tools/dev/gen_class.pl>.
16 27
17   -=head2 Functions
18   -
19   -The following functions are exported:
20   -
21   -=over 4
22   -
23 28 =cut
24 29
25   -package Parrot::Vtable;
26   -
27   -use strict;
28   -use warnings;
29   -
30   -use base qw( Exporter );
31   -
32   -use FileHandle;
33   -
34   -our @EXPORT = qw(parse_vtable vtbl_defs vtbl_struct vtbl_macros vtbl_embed);
35   -
36 30 sub make_re {
37 31 my $re = shift;
38 32 my $comp_re = qr/$re/;
@@ -61,15 +55,44 @@ sub parse_attrs {
61 55 return $result;
62 56 }
63 57
64   -=item C<parse_vtable($file)>
  58 +=head1 FUNCTIONS
  59 +
  60 +The following functions are exported:
65 61
66   -Returns a reference to an array containing
  62 +=head2 C<parse_vtable<()>
  63 +
  64 +=over 4
67 65
68   - [ return_type method_name parameters section MMD_type attributes ]
  66 +=item * Purpose
  67 +
  68 +Parse vtable.
  69 +
  70 +=item * Arguments
  71 +
  72 +String holding path to vtable file.
  73 +
  74 +=item * Return Value
  75 +
  76 +Reference to an array containing:
  77 +
  78 + [
  79 + return_type
  80 + method_name
  81 + parameters
  82 + section
  83 + MMD_type
  84 + attributes
  85 + ]
69 86
70 87 for each vtable function defined in C<$file>. If it is not an MMD method,
71 88 C<MMD_type> is -1.
72 89
  90 +=item * Comment
  91 +
  92 +Used in C<Parrot::Pmc2c::VTable::build()>.
  93 +
  94 +=back
  95 +
73 96 =cut
74 97
75 98 sub parse_vtable {
@@ -119,10 +142,32 @@ sub parse_vtable {
119 142 return [ @{$mmd}, sort { $a->[1] cmp $b->[1] } @{$vtable} ];
120 143 }
121 144
122   -=item C<vtbl_defs($vtable)>
  145 +# all encapsulated below here
123 146
124   -Returns the C C<typedef> definitions for the elements in the referenced
125   -vtable array.
  147 +=head2 C<vtbl_defs()>
  148 +
  149 +=over 4
  150 +
  151 +=item * Purpose
  152 +
  153 +Compose the C C<typedef> definitions for the elements in the referenced vtable
  154 +array.
  155 +
  156 +=item * Arguments
  157 +
  158 +Reference to an array. This array ref is the output of this package's
  159 +C<parse_vtable> method.
  160 +
  161 +=item * Return Value
  162 +
  163 +Returns string holding the C C<typedef> definitions for the elements in the
  164 +referenced vtable array.
  165 +
  166 +Used in F<tools/build/vtable_h.pl>.
  167 +
  168 +=item * Comment
  169 +
  170 +=back
126 171
127 172 =cut
128 173
@@ -151,10 +196,30 @@ sub vtbl_defs {
151 196 return $defs;
152 197 }
153 198
154   -=item C<vtbl_struct($vtable)>
  199 +=head2 C<vtbl_struct()>
155 200
156   -Returns the C C<struct> definitions for the elements in the referenced
157   -vtable array.
  201 +=over 4
  202 +
  203 +=item * Purpose
  204 +
  205 +Compose the C C<struct> definitions for the elements in the referenced vtable
  206 +array.
  207 +
  208 +=item * Arguments
  209 +
  210 +Reference to an array. This array ref is the output of this package's
  211 +C<parse_vtable> method.
  212 +
  213 +=item * Return Value
  214 +
  215 +Returns a string holding the C C<struct> definitions for the elements in the
  216 +referenced vtable array.
  217 +
  218 +Used in F<tools/build/vtable_h.pl>.
  219 +
  220 +=item * Comment
  221 +
  222 +=back
158 223
159 224 =cut
160 225
@@ -206,11 +271,31 @@ EOF
206 271 return $struct;
207 272 }
208 273
209   -=item C<vtbl_macros($vtable)>
  274 +=head2 C<vtbl_macros()>
  275 +
  276 +=over 4
  277 +
  278 +=item * Purpose
210 279
211   -Returns the C C<#define> definitions for the elements in the referenced
  280 +Compose the C C<#define> definitions for the elements in the referenced vtable
  281 +array.
  282 +
  283 +=item * Arguments
  284 +
  285 +Reference to an array. This array ref is the output of this package's
  286 +C<parse_vtable> method.
  287 +
  288 +=item * Return Value
  289 +
  290 +String holding the C C<#define> definitions for the elements in the referenced
212 291 vtable array.
213 292
  293 +Used in F<tools/build/vtable_h.pl>.
  294 +
  295 +=item * Comment
  296 +
  297 +=back
  298 +
214 299 =cut
215 300
216 301 sub vtbl_macros {
@@ -288,10 +373,26 @@ EOM
288 373 $macros;
289 374 }
290 375
291   -=item C<vtbl_embed($vtable)>
  376 +=head2 C<vtbl_embed()>
  377 +
  378 +=over 4
  379 +
  380 +=item * Purpose
  381 +
  382 +=item * Arguments
  383 +
  384 +Reference to an array. This array ref is the output of this package's
  385 +C<parse_vtable> method.
  386 +
  387 +=item * Return Value
  388 +
  389 +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.
  390 +
  391 +Used in F<tools/build/vtable_extend.pl>.
292 392
293   -Returns the C function definitions to call the vtable functions on a PMC for the
294   -elements in the referenced vtable array.
  393 +=item * Comment
  394 +
  395 +=back
295 396
296 397 =cut
297 398
@@ -391,20 +492,20 @@ sub parse_params {
391 492 return @params;
392 493 }
393 494
394   -=back
395   -
396 495 =head1 SEE ALSO
397 496
398 497 =over 4
399 498
400 499 =item F<tools/build/vtable_extend.pl>
401 500
402   -=item F<tools/build/pmc2c.pl>
403   -
404 501 =item F<tools/build/vtable_h.pl>
405 502
  503 +=item F<tools/build/pmc2c.pl>
  504 +
406 505 =item F<tools/dev/gen_class.pl>
407 506
  507 +=back
  508 +
408 509 =cut
409 510
410 511 1;

0 comments on commit 114e8c6

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