cvsuser 04/11/07 09:40:03
Modified: tools/dev parrot_api.pl Log: Add minimal documentation. Revision Changes Path 1.2 +66 -1 parrot/tools/dev/parrot_api.pl Index: parrot_api.pl =================================================================== RCS file: /cvs/public/parrot/tools/dev/parrot_api.pl,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- parrot_api.pl 7 Nov 2004 17:23:52 -0000 1.1 +++ parrot_api.pl 7 Nov 2004 17:40:03 -0000 1.2 @@ -1,6 +1,71 @@ #!/usr/bin/perl -w # Copyright: 2004 The Perl Foundation. All Rights Reserved. -# $Id: parrot_api.pl,v 1.1 2004/11/07 17:23:52 jhi Exp $ +# $Id: parrot_api.pl,v 1.2 2004/11/07 17:40:03 jhi Exp $ + +=head1 NAME + +tools/dev/parrot_api.pl - Display Parrot API (symbols) + +=head1 SYNOPSIS + + % perl tools/dev/parrot_api.pl [libfile] + +=head1 DESCRIPTION + +Displays the API (the visible symbols, code or data) of the Parrot lib, +. + +First finds out the Parrot public embedding API as described in the +F<include/parrot/embed.h>, then finds out the visible symbols in +the Parrot lib (by default F<blib/lib/libparrot.a>), and then +cross-references the dubious API symbols according to the following +categories: + +=over 4 + +=item Missing Parrot API + +API listed in F<include/parrot/embed.h> but not defined in the Parrot lib. + +Why is the planned public API not implemented? + +=item No Parrot Prefix + +API has no C<Parrot_> prefix. + +If code: if the API is really to be public, prefix it with <Parrot_> +(and not something else), if not, make it private (local). + +If data, consider making the data either constant or heap. + +=item No Parrot API + +API defined in the lib but not in F<inlucde/parrot/embed.h>. + +If code, consider making the API private. +If data, consider making the data constant and/or heap. + +=item Uninitialized Modifiable Data + +Data symbol that is not initialized with data. + +Consider making the data constant and/or heap (and accessed through an API). + +=item Initialized Modifiable Data + +Data symbol that is initialized with data, but modifiable. + +Consider making the data constant and/or heap (and accessed through an API). + +=back + +Uses F<tools/dev/nm.pl> to list the symbols. + +=head1 HISTORY + +Author: Jarkko Hietaniemi. + +=cut use strict;
