cvsuser 05/03/13 01:16:28
Modified: tools/dev parrot_api.pl
Log:
More documentation, skip now 'undeclared Parrotish' interfaces
from the warnings (to avoid getting bazillion errors from the
classes/*.o objects).
Revision Changes Path
1.7 +32 -25 parrot/tools/dev/parrot_api.pl
Index: parrot_api.pl
===================================================================
RCS file: /cvs/public/parrot/tools/dev/parrot_api.pl,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -r1.6 -r1.7
--- parrot_api.pl 8 Mar 2005 06:51:10 -0000 1.6
+++ parrot_api.pl 13 Mar 2005 09:16:28 -0000 1.7
@@ -1,6 +1,6 @@
#!/usr/bin/perl -w
# Copyright: 2004 The Perl Foundation. All Rights Reserved.
-# $Id: parrot_api.pl,v 1.6 2005/03/08 06:51:10 jhi Exp $
+# $Id: parrot_api.pl,v 1.7 2005/03/13 09:16:28 jhi Exp $
=head1 NAME
@@ -34,9 +34,10 @@
Either the API listing is wrong or the implementation is missing.
-=item No Parrot Prefix
+=item No Parrotish Prefix
-The API is implemented but has no C<Parrot_> prefix.
+The API is implemented but has no C<Parrot_> prefix (or prefix deemed
+Parroty enough, like C<PDB_>, C<PF_>, C<PIO_>, and C<PackFile>).
If code: see L</"Public or Private">.
@@ -87,29 +88,35 @@
Consider making the data const(ant) heap (and accessed through a real
API that takes care of synchronization, data as such is not a good API
-unless it's constant). Think multithreaded access, or just plan
-reentrancy (think recursion). Often you can collect data fields into
-a "context" structure that is either explicitly passed between
-functions or implicitly retrieved from a global API.
+unless it's constant).
-=head1 DEPENDENCIES
+Think multithreaded access, or just plain reentrancy (think recursion).
-Uses F<tools/dev/nm.pl> to list the symbols.
+Often you can collect a group of data fields into a "context" (or
+"descriptor", "handle", "session", "state") structure that is either
+explicitly passed between functions or implicitly retrieved from a
+global API. Encapsulating data like this is good: it allows passing,
+synchronzing, and duplicating state much easier, and makes it clearer
+into which context the data belongs.
+
+For APIs purely internal to Parrot, try using C<const> in function
+prototypes as often as possible to catch inadvertent data modification
+by callers. For APIs that cross into the operating system and/or
+external libraries, you usually cannot go overly C<const> because of
+portability issues.
-=head1 TODO
+Make your strings and arrays of strings (or similar inlined data)
+C<const> -- for the latter, remember that you need two consts:
-=over 4
+ const char* const foo[] = { "foo", "bar" };
-=item *
+=head1 DEPENDENCIES
-There are a lot of warnings given from "core class" cases like
+Uses F<tools/dev/nm.pl> to list the symbols.
- Parrot_Array_class_init array.o
+=head1 TODO
-which are probably okay. This tool should be taught about these
-cases: how to find out which APIs are B<supposed> to be found from
-such "core class" objects? But in any case, even those objects should
-B<NOT> have any data symbols visible.
+=over 4
=item *
@@ -195,7 +202,7 @@
printf "+++ Parrot API: %d +++\n", scalar @ParrotAPI;
if (@ParrotAPI) {
for my $api (@ParrotAPI) {
- printf "%s\t%s\n", $api, $API{$api} || "-";
+ printf "%s\t%s\tOK\n", $api, $API{$api} || "-";
}
}
@@ -213,7 +220,7 @@
unless ($api =~ $ParrotPrefix) {
push @NoParrotPrefix, $api;
}
- unless (exists $ParrotAPI{$api}) {
+ unless (exists $ParrotAPI{$api} || $api =~ $ParrotPrefix) {
push @UnParrotAPI, $api;
}
}
@@ -221,35 +228,35 @@
if (@NoParrotAPI) {
printf "--- Missing Parrot API: %d ---\n", scalar @NoParrotAPI;
for my $api (@NoParrotAPI) {
- printf "%s\t%s\n", $api, "-";
+ printf "%s\t%s\tMISSING_API\n", $api, "-";
}
}
if (@NoParrotPrefix) {
printf "--- No Parrot prefix: %d ---\n", scalar @NoParrotPrefix;
for my $api (@NoParrotPrefix) {
- printf "%s\t%s\n", $api, $API{$api};
+ printf "%s\t%s\tBAD_PREFIX\n", $api, $API{$api};
}
}
if (@UnParrotAPI) {
printf "--- No Parrot API: %d ---\n", scalar @UnParrotAPI;
for my $api (@UnParrotAPI) {
- printf "%s\t%s\n", $api, $API{$api};
+ printf "%s\t%s\tNO_API\n", $api, $API{$api};
}
}
if (keys %DataB) {
printf "--- Uninitialized Modifiable Data: %d ---\n", scalar keys %DataB;
for my $api (sort keys %DataB) {
- printf "%s\t%s\n", $api, $DataB{$api};
+ printf "%s\t%s\tUMD\n", $api, $DataB{$api};
}
}
if (keys %DataD) {
printf "--- Initialized Modifiable Data: %d ---\n", scalar keys %DataD;
for my $api (sort keys %DataD) {
- printf "%s\t%s\n", $api, $DataD{$api};
+ printf "%s\t%s\tIMD\n", $api, $DataD{$api};
}
}
