You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucy.apache.org by ma...@apache.org on 2011/12/19 22:18:16 UTC

[lucy-commits] svn commit: r1220952 - in /incubator/lucy/trunk/clownfish: perl/lib/ perl/lib/Clownfish/ src/

Author: marvin
Date: Mon Dec 19 21:18:15 2011
New Revision: 1220952

URL: http://svn.apache.org/viewvc?rev=1220952&view=rev
Log:
Migrate CFC docs into C header files.

Move documentation for primary CFC components out of the .pm files and into
the .h files.  This migration is not lossless because most of the code samples
get eliminated, but we need to document the C code and a DRY violation to keep
the Perl interface docs would surely lead to bitrot.

Modified:
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Base.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CBlock.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Class.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/DocuComment.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Dumpable.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/File.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Function.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Hierarchy.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Method.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/ParamList.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Parcel.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Parser.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Symbol.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Type.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Util.pm
    incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Variable.pm
    incubator/lucy/trunk/clownfish/src/CFCBase.h
    incubator/lucy/trunk/clownfish/src/CFCCBlock.h
    incubator/lucy/trunk/clownfish/src/CFCClass.h
    incubator/lucy/trunk/clownfish/src/CFCDocuComment.h
    incubator/lucy/trunk/clownfish/src/CFCDumpable.h
    incubator/lucy/trunk/clownfish/src/CFCFile.h
    incubator/lucy/trunk/clownfish/src/CFCFunction.h
    incubator/lucy/trunk/clownfish/src/CFCHierarchy.h
    incubator/lucy/trunk/clownfish/src/CFCMethod.h
    incubator/lucy/trunk/clownfish/src/CFCParamList.h
    incubator/lucy/trunk/clownfish/src/CFCParcel.h
    incubator/lucy/trunk/clownfish/src/CFCParser.h
    incubator/lucy/trunk/clownfish/src/CFCSymbol.h
    incubator/lucy/trunk/clownfish/src/CFCType.h
    incubator/lucy/trunk/clownfish/src/CFCUtil.h
    incubator/lucy/trunk/clownfish/src/CFCVariable.h

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish.pm Mon Dec 19 21:18:15 2011
@@ -49,6 +49,8 @@ BEGIN { XSLoader::load( 'Clownfish', '0.
         );
     }
 
+    # Verify that named parameters exist in a defaults hash.  Returns false
+    # and sets $@ if a problem is detected.
     sub verify_args {
         my $defaults = shift;    # leave the rest of @_ intact
 
@@ -306,6 +308,11 @@ BEGIN { XSLoader::load( 'Clownfish', '0.
         return _singleton( @args{qw( name cnick )} );
     }
 
+    #    $parcel = Clownfish::Parcel->aquire($parcel_name_or_parcel_object);
+    #
+    # Aquire a parcel one way or another.  If the supplied argument is a
+    # Parcel, return it.  If it's not defined, return the default Parcel.  If
+    # it's a name, invoke singleton().
     sub acquire {
         my ( undef, $thing ) = @_;
         if ( !defined $thing ) {

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Base.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Base.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Base.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Base.pm Mon Dec 19 21:18:15 2011
@@ -18,17 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Base - Base class for all CFC objects.
-
-=head1 DESCRIPTION
-
-    # TODO
-
-=cut
-

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CBlock.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CBlock.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CBlock.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CBlock.pm Mon Dec 19 21:18:15 2011
@@ -18,54 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::CBlock - A block of embedded C code.
-
-=head1 DESCRIPTION
-
-CBlock exists to support embedding literal C code within Clownfish header
-files:
-
-    class Crustacean::Lobster {
-        /* ... */
-
-        /** Give a lobstery greeting.
-         */
-        inert inline void
-        say_hello(Lobster *self);
-    }
-
-    __C__
-    #include <stdio.h>
-    static CHY_INLINE void
-    crust_Lobster_say_hello(crust_Lobster *self)
-    {
-        printf("Prepare to die, human scum.\n");
-    }
-    __END_C__
-
-=head1 METHODS
-
-=head2 new
-
-    my $c_block = Clownfish::CBlock->new(
-        contents => $text,
-    );
-
-=over
-
-=item * B<contents> - Raw C code.
-
-=back
-
-=head2 get_contents
-
-Accessor.
-
-=cut
-

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Class.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Class.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Class.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Class.pm Mon Dec 19 21:18:15 2011
@@ -18,217 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Class - An object representing a single class definition.
-
-=head1 CONSTRUCTORS
-
-Clownfish::Class objects are stored as quasi-singletons, one for each
-unique parcel/class_name combination.
-
-=head2 fetch_singleton 
-
-    my $class = Clownfish::Class->fetch_singleton(
-        parcel     => 'Crustacean',
-        class_name => 'Crustacean::Lobster::LobsterClaw',
-    );
-
-Retrieve a Class, if one has already been created.
-
-=head2 create
-
-    my $class = Clownfish::Class->create(
-        parcel     => 'Crustacean',                        # default: special
-        class_name => 'Crustacean::Lobster::LobsterClaw',  # required
-        cnick      => 'LobClaw',                           # default: special
-        exposure   => 'public',                            # default: 'parcel'
-        source_class      => undef,              # default: same as class_name
-        parent_class_name => 'Crustacean::Claw', # default: undef
-        inert             => undef,              # default: undef
-        docucomment       => $documcom,          # default: undef,
-    );
-
-Create and register a quasi-singleton.  May only be called once for each
-unique parcel/class_name combination.
-
-=over
-
-=item * B<parcel>, B<class_name>, B<cnick>, B<exposure> - see
-L<Clownfish::Symbol>.
-
-=item * B<source_class> - The name of the class that owns the file in which
-this class was declared.  Should be "Foo" if "Foo::FooJr" is defined in
-C<Foo.cfh>.
-
-=item * B<parent_class_name> - The name of this class's parent class.  Needed
-in order to establish the class hierarchy.
-
-=item * B<inert> - Should be true if the class is inert, i.e. cannot be
-instantiated.
-
-=item * B<docucomment> - A Clownfish::DocuComment describing this Class.
-
-=back
-
-=head1 METHODS
-
-=head2 get_cnick get_struct_sym get_parent_class_name get_source_class
-get_docucomment get_parent get_autocode inert final
-
-Accessors.
-
-=head2 set_parent
-
-    $class->set_parent($ancestor);
-
-Set the parent class.
-
-=head2 add_child
-
-    $class->add_child($child_class);
-
-Add a child class. 
-
-=head2 add_method
-
-    $class->add_method($method);
-
-Add a Method to the class.  Valid only before grow_tree() is called.
-
-=head2 add_function
-
-    $class->add_function($function);
-
-Add a Function to the class.  Valid only before grow_tree() is called.
-
-=head2 add_member_var
-
-    $class->add_member_var($var);
-
-Add a member variable to the class.  Valid only before grow_tree() is called.
-
-=head2 add_inert_var
-
-    $class->add_inert_var($var);
-
-Add an inert (class) variable to the class.  Valid only before grow_tree() is
-called.
-
-=head2 add_attribute
-
-    $class->add_attribute($var, $value);
-
-Add an arbitrary attribute to the class.
-
-=head2 function 
-
-    my $do_stuff_function = $class->function("do_stuff");
-
-Return the inert Function object for the supplied C<micro_sym>, if any.
-
-=head2 method
-
-    my $pinch_method = $class->method("Pinch");
-
-Return the Method object for the supplied C<micro_sym> / C<macro_sym>, if any.
-
-=head2 novel_method
-
-    my $pinch_method = $class->novel_method("Pinch");
-
-Return a Method object if the Method corresponding to the supplied string is
-novel.
-
-=head2 children 
-
-    my $child_classes = $class->children;
-
-Return an array of all child classes.
-
-=head2 functions
-
-    my $functions = $class->functions;
-
-Return an array of all (inert) functions.
-
-=head2 methods
-
-    my $methods = $class->methods;
-
-Return an array of all methods.
-
-=head2 inert_vars
-
-    my $inert_vars = $class->inert_vars;
-
-Return an array of all inert (shared, class) variables.
-
-=head2 member_vars
-
-    my $members = $class->member_vars;
-
-Return an array of all member variables.
-
-=head2 novel_methods
-
-    my $novel_methods = $class->novel_methods;
-
-Return an array of all novel methods.
-
-=head2 novel_member_vars
-
-    my $new_members = $class->novel_member_vars;
-
-Return an array of all novel member variables.
-
-=head2 grow_tree
-
-    $class->grow_tree;
-
-Bequeath all inherited methods and members to children.
-
-=head2 tree_to_ladder
-
-    my $ordered = $class->tree_to_ladder;
-
-Return this class and all its child classes as an array, where all children
-appear after their parent nodes.
-
-=head2 include_h
-
-    my $relative_path = $class->include_h;
-
-Return a relative path to a C header file, appropriately formatted for a
-pound-include directive.
-
-=head2 append_autocode
-
-    $class->append_autocode($code);
-
-Append auxiliary C code.
-
-=head2 short_vtable_var
-
-The short name of the global VTable object for this class.
-
-=head2 full_vtable_var
-
-Fully qualified vtable variable name, including the parcel prefix.
-
-=head2 full_vtable_type
-
-The fully qualified C type specifier for this class's vtable, including the
-parcel prefix.  Each vtable needs to have its own type because each has a
-variable number of methods at the end of the struct, and it's not possible to
-initialize a static struct with a flexible array at the end under C89.
-
-=head2 full_struct_sym
-
-Fully qualified struct symbol, including the parcel prefix.
-
-=cut

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/DocuComment.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/DocuComment.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/DocuComment.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/DocuComment.pm Mon Dec 19 21:18:15 2011
@@ -18,69 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::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 = Clownfish::DocuComment->parse($text);
-
-=head1 CONSTRUCTORS 
-
-=head2 parse 
-
-    my $self = Clownfish::DocuComment->parse($text);
-
-Parse comment text.
-
-=head2 new
-
-    my $self = Clownfish::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.
-
-=cut
-

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Dumpable.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Dumpable.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Dumpable.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Dumpable.pm Mon Dec 19 21:18:15 2011
@@ -18,50 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Dumpable - Auto-generate code for "dumpable" classes.
-
-=head1 SYNOPSIS
-
-    my $dumpable = Clownfish::Dumpable->new;
-    for my $class ( grep { $_->has_attribute('dumpable') } @classes ) {
-        $dumpable->add_dumpables($class);
-    }
-
-=head1 DESCRIPTION
-
-If a class declares that it has the attribute "dumpable", but does not declare
-either Dump or Load(), Clownfish::Dumpable will attempt to auto-generate
-those methods if methods inherited from the parent class do not suffice.
-
-    class Foo::Bar inherits Foo : dumpable {
-        Thing *thing;
-
-        public inert incremented Bar*
-        new();
-
-        void
-        Destroy(Bar *self);
-    }
-
-=head1 METHODS
-
-=head2 new
-
-    my $dumpable = Clownfish::Dumpable->new;
-
-Constructor.  Takes no arguments.
-
-=head2 add_dumpables
-
-    $dumpable->add_dumpables($dumpable_class);
-
-Analyze a class with the attribute "dumpable" and add Dump() or Load() methods
-as necessary.
-
-=cut

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/File.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/File.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/File.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/File.pm Mon Dec 19 21:18:15 2011
@@ -18,88 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::File - Structured representation of the contents of a
-Clownfish source file.
-
-=head1 DESCRIPTION
-
-An abstraction representing a file which contains Clownfish code.
-
-=head1 METHODS
-
-=head2 new
-
-    my $file_obj = Clownfish::File->new(
-        source_class => 'Crustacean::Lobster',    # required
-    );
-
-=over
-
-=item * B<source_class> - The class name associated with the source file,
-regardless of how what classes are defined in the source file. Example: If
-source_class is "Foo::Bar", that implies that the source file could be found
-at 'Foo/Bar.cfh' within the source directory and that the output C header file
-should be 'Foo/Bar.h' within the target include directory.
-
-=back
-
-=head2 add_block
-
-    $file_obj->add_block($block);
-
-Add an element to the blocks array.  The block must be either a
-Clownfish::Class, a Clownfish::Parcel, or a Clownfish::CBlock.
-
-=head2 blocks
-
-    my $blocks = $file->blocks;
-
-Return all blocks as an arrayref.
-
-=head2 classes
-
-    my $classes = $file->classes;
-
-Return all Clownfish::Class blocks from the file as an arrayref.
-
-=head2 get_modified set_modified
-
-Accessors for the file's "modified" property, which is initially false.
-
-=head2 get_source_class
-
-Accessor.
-
-=head2 c_path h_path cfh_path
-
-    # '/path/to/Source/Class.c', etc.
-    my $c_path   = $file->c_path('/path/to');
-    my $h_path   = $file->h_path('/path/to');
-    my $cfh_path = $file->cfh_path('/path/to');
-
-Given a base directory, return a path name derived from the File's
-source_class with the specified extension.
-
-=head2 guard_name
-
-    # e.g. "H_CRUSTACEAN_LOBSTER"
-    my $guard_name = $file->guard_name
-
-Return a string used for an include guard in a C header, unique per file.
-
-=head2 guard_start
-
-Return a string opening the include guard.
-
-=head2 guard_close
-
-Return a string closing the include guard.  Other classes count on being able
-to match this string.
-
-=cut

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Function.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Function.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Function.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Function.pm Mon Dec 19 21:18:15 2011
@@ -18,72 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Function - Metadata describing a function.
-
-=head1 METHODS
-
-=head2 new
-
-    my $type = Clownfish::Function->new(
-        class_name  => 'Crustacean::Lobster::LobsterClaw',  # required
-        class_cnick => 'LobClaw',                           # default: special
-        return_type => $int_type,                           # required
-        param_list  => $param_list,                         # required
-        micro_sym   => 'compare',                           # required
-        docucomment => $docucomment,                        # default: undef
-        parcel      => 'Crustacean',                        # default: special
-        exposure    => 'public',                            # default: parcel
-        inline      => 1,                                   # default: false
-    );
-
-=over
-
-=item * B<class_name> - The full name of the class in whose namespace the
-function resides.
-
-=item * B<class_cnick> - The C nickname for the class. 
-
-=item * B<return_type> - A L<Clownfish::Type> representing the function's
-return type.
-
-=item * B<param_list> - A L<Clownfish::ParamList> representing the
-function's argument list.
-
-=item * B<micro_sym> - The lower case name of the function, without any
-namespacing prefixes.
-
-=item * B<docucomment> - A L<Clownfish::DocuComment> describing the
-function.
-
-=item * B<parcel> - A L<Clownfish::Parcel> or a parcel name.
-
-=item * B<exposure> - The function's exposure (see L<Clownfish::Symbol>).
-
-=item * B<inline> - Should be true if the function should be inlined by the
-compiler.
-
-=back
-
-=head2 get_return_type get_param_list get_docucomment inline 
-
-Accessors.
-
-=head2 void
-
-Returns true if the function has a void return type, false otherwise.
-
-=head2 full_func_sym
-
-A synonym for full_sym().
-
-=head2 short_func_sym
-
-A synonym for short_sym().
-
-=cut

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Hierarchy.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Hierarchy.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Hierarchy.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Hierarchy.pm Mon Dec 19 21:18:15 2011
@@ -18,65 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Hierarchy - A class hierarchy.
-
-=head1 DESCRIPTION
-
-A Clownfish::Hierarchy consists of all the classes defined in files within
-a source directory and its subdirectories.
-
-There may be more than one tree within the Hierarchy, since all "inert"
-classes are root nodes, and since Clownfish does not officially define any
-core classes itself from which all instantiable classes must descend.
-
-=head1 METHODS
-
-=head2 new
-
-    my $hierarchy = Clownfish::Hierarchy->new(
-        source => undef,    # required
-        dest   => undef,    # required
-    );
-
-=over
-
-=item * B<source> - The directory we begin reading files from.
-
-=item * B<dest> - The directory where the autogenerated files will be written.
-
-=back
-
-=head2 build
-
-    $hierarchy->build;
-
-Parse every Clownfish header file which can be found under C<source>, building
-up the object hierarchy.
-
-=head2 ordered_classes
-
-    my $classes = $hierarchy->ordered_classes;
-
-Return all Classes as an array with the property that every parent class will
-precede all of its children.
-
-=head2 propagate_modified
-
-    $hierarchy->propagate_modified($modified);
-
-Visit all File objects in the hierarchy.  If a parent node is modified, mark
-all of its children as modified.  
-
-If the supplied argument is true, mark all Files as modified.
-
-=head2 get_source get_dest
-
-Accessors.
-
-=cut

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Method.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Method.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Method.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Method.pm Mon Dec 19 21:18:15 2011
@@ -18,156 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Method - Metadata describing an instance method.
-
-=head1 DESCRIPTION
-
-Clownfish::Method is a specialized subclass of Clownfish::Function, with
-the first argument required to be an Obj.
-
-When compiling Clownfish code to C, Method objects generate all the code
-that Function objects do, but also create symbols for indirect invocation via
-VTable.
-
-=head1 METHODS
-
-=head2 new
-
-    my $type = Clownfish::Method->new(
-        parcel      => 'Crustacean',                       # default: special
-        class_name  => 'Crustacean::Lobster::LobsterClaw', # required
-        class_cnick => 'LobClaw',                          # default: special
-        macro_sym   => 'Pinch',                            # required
-        return_type => $void_type,                         # required
-        param_list  => $param_list,                        # required
-        exposure    => undef,                              # default: 'parcel'
-        docucomment => $docucomment,                       # default: undef
-        abstract    => undef,                              # default: undef
-        final       => 1,                                  # default: undef
-    );
-
-=over
-
-=item * B<param_list> - A Clownfish::ParamList.  The first element must be an
-object of the class identified by C<class_name>.
-
-=item * B<macro_sym> - The mixed case name which will be used when invoking the
-method.
-
-=item * B<abstract> - Indicate whether the method is abstract.
-
-=item * B<final> - Indicate whether the method is final.
-
-=item * B<parcel>, B<class_name>, B<class_cnick>, B<return_type>,
-B<docucomment>, - see L<Clownfish::Function>.
-
-=back
-
-=head2 abstract final get_macro_sym 
-
-Getters.
-
-=head2 novel
-
-Returns true if the method's class is the first in the inheritance hierarchy
-in which the method was declared -- i.e. the method is neither inherited nor
-overridden.
-
-=head2 self_type
-
-Return the L<Clownfish::Type> for C<self>.
-
-=head2 short_method_sym
-
-    # e.g. "LobClaw_Pinch"
-    my $short_sym = $method->short_method_sym("LobClaw");
-
-Returns the symbol used to invoke the method (minus the parcel Prefix).
-
-=head2 full_method_sym
-
-    # e.g. "Crust_LobClaw_Pinch"
-    my $full_sym = $method->full_method_sym("LobClaw");
-
-Returns the fully-qualified symbol used to invoke the method.
-
-=head2 full_offset_sym
-
-    # e.g. "Crust_LobClaw_Pinch_OFFSET"
-    my $offset_sym = $method->full_offset_sym("LobClaw");
-
-Returns the fully qualified name of the variable which stores the method's
-vtable offset.
-
-=head2 full_callback_sym
-
-    # e.g. "crust_LobClaw_pinch_CALLBACK"
-    my $callback_sym = $method->full_calback_sym("LobClaw");
-
-Returns the fully qualified name of the variable which stores the method's
-Callback object.
-
-=head2 full_override_sym
-
-    # e.g. "crust_LobClaw_pinch_OVERRIDE"
-    my $override_func_sym = $method->full_override_sym("LobClaw");
-
-Returns the fully qualified name of the function which implements the callback
-to the host in the event that a host method has been defined which overrides
-this method.
-
-=head2 short_typedef
-
-    # e.g. "Claw_pinch_t"
-    my $short_typedef = $method->short_typedef;
-
-Returns the typedef symbol for this method, which is derived from the class
-nick of the first class in which the method was declared.
-
-=head2 full_typedef
-
-    # e.g. "crust_Claw_pinch_t"
-    my $full_typedef = $method->full_typedef;
-
-Returns the fully-qualified typedef symbol including parcel prefix.
-
-=head2 override
-
-    $method->override($method_being_overridden);
-
-Let the Method know that it is overriding a method which was defined in a
-parent class, and verify that the override is valid.
-
-All methods start out believing that they are "novel", because we don't know
-about inheritance until we build the hierarchy after all files have been
-parsed.  override() is a way of going back and relabeling a method as
-overridden when new information has become available: in this case, that a
-parent class has defined a method with the same name.
-
-=head2 finalize
-
-    my $final_method = $method->finalize;
-
-As with override, above, this is for going back and changing the nature of a
-Method after new information has become available -- typically, when we
-discover that the method has been inherited by a "final" class.
-
-However, we don't modify the original Method as with override().  Inherited
-Method objects are shared between parent and child classes; if a shared Method
-object were to become final, it would interfere with its own inheritance.  So,
-we make a copy, slightly modified to indicate that it is "final".
-
-=head2 compatible
-
-    confess("Can't override") unless $method->compatible($other);
-
-Returns true if the methods have signatures and attributes which allow
-one to override the other.
-
-=cut

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/ParamList.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/ParamList.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/ParamList.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/ParamList.pm Mon Dec 19 21:18:15 2011
@@ -18,66 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::ParamList - parameter list.
-
-=head1 DESCRIPTION
-
-=head1 METHODS
-
-=head2 new
-
-    my $param_list = Clownfish::ParamList->new(
-        variadic => 1,    # default: false
-    );
-
-=over
-
-=item * B<variadic> - Should be true if the function is variadic.
-
-=back
-
-=head2 add_param
-
-    $param_list->add_param( $variable, $value );
-
-Add a parameter to the ParamList.
-
-=over
-
-=item * B<variable> - A L<Clownfish::Variable>. 
-
-=item * B<value> - The default value for the parameter, which should be undef
-if there is no such value and the parameter is required.
-
-=back
-
-=head2 get_variables get_initial_values variadic
-
-Accessors. 
-
-=head2 num_vars
-
-Return the number of variables in the ParamList, including "self" for methods.
-
-=head2 to_c
-
-    # Prints "Obj* self, Foo* foo, Bar* bar".
-    print $param_list->to_c;
-
-Return a list of the variable's types and names, joined by commas.
-
-=head2 name_list
-
-    # Prints "self, foo, bar".
-    print $param_list->name_list;
-
-Return the variable's names, joined by commas.
-
-=cut
-

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Parcel.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Parcel.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Parcel.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Parcel.pm Mon Dec 19 21:18:15 2011
@@ -18,77 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Parcel - Collection of code.
-
-=head1 DESCRIPTION
-
-A Parcel is a cohesive collection of code, which could, in theory, be
-published as as a single entity.
-
-Clownfish supports two-tier manual namespacing, using a prefix, an optional
-class nickname, and the local symbol:
-
-  prefix_ClassNick_local_symbol
-  
-Clownfish::Parcel supports the first tier, specifying initial prefixes.
-These prefixes come in three capitalization variants: prefix_, Prefix_, and
-PREFIX_.
-
-=head1 CLASS METHODS
-
-=head2 singleton 
-
-    Clownfish::Parcel->singleton(
-        name  => 'Crustacean',
-        cnick => 'Crust',
-    );
-
-Add a Parcel singleton to a global registry.  May be called multiple times,
-but only with compatible arguments.
-
-=over
-
-=item *
-
-B<name> - The name of the parcel.
-
-=item *
-
-B<cnick> - The C nickname for the parcel, which will be used as a prefix for
-generated global symbols.  Must be mixed case and start with a capital letter.
-Defaults to C<name>.
-
-=back
-
-=head2 default_parcel
-
-   $parcel ||= Clownfish::Parcel->default_parcel;
-
-Return the singleton for default parcel, which has no prefix.
-
-=head1 OBJECT METHODS
-
-=head2 get_prefix get_Prefix get_PREFIX
-
-Return one of the three capitalization variants for the parcel's prefix.
-
-=head2 acquire
-
-    $parcel = Clownfish::Parcel->aquire($parcel_name_or_parcel_object);
-
-Aquire a parcel one way or another.  If the supplied argument is a Parcel,
-return it.  If it's not defined, return the default Parcel.  If it's a name,
-invoke singleton().
-
-=head2 get_name get_cnick
-
-Accessors.
-
-=cut
-

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Parser.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Parser.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Parser.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Parser.pm Mon Dec 19 21:18:15 2011
@@ -18,29 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Parser - Parse Clownfish header files.
-
-=head1 SYNOPSIS
-
-     my $class_def = $parser->class($class_text);
-
-=head1 DESCRIPTION
-
-Clownfish::Parser is a combined lexer/parser which parses Clownfish header
-files.  It is not at all strict, as it relies heavily on the C parser to pick
-up errors such as misspelled type names.
-
-=head1 METHODS
-
-=head2 new
-
-Constructor, takes no arguments.
-
-=cut
-

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Symbol.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Symbol.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Symbol.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Symbol.pm Mon Dec 19 21:18:15 2011
@@ -18,86 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Symbol - Base class for Clownfish symbols.
-
-=head1 DESCRIPTION
-
-Clownfish::Symbol serves as a parent class for entities which may live in the
-global namespace, such as classes, functions, methods, and variables.
-
-=head1 CONSTRUCTOR
-
-    my $symbol = Clownfish::Symbol->new(
-        parcel      => 'Crustacean',             # default: special
-        exposure    => 'parcel',                 # required
-        class_name  => 'Crustacean::Lobster',    # default: undef
-        class_cnick => undef,                    # default: special
-        micro_sym   => 'average_lifespan',       # required
-    );
-
-=over
-
-=item * B<parcel> - A Clownfish::Parcel, or a string that can be used to
-create/retrieve one.  If not supplied, will be assigned to the default Parcel.
-
-=item * B<exposure> - The scope in which the symbol is exposed.  Must be
-'public', 'parcel', 'private', or 'local'.
-
-=item * B<class_name> - A optional class name, consisting of one or more
-components separated by "::".  Each component must start with a capital
-letter, contain at least one lower-case letter, and consist entirely of the
-characters [A-Za-z0-9].
-
-=item * B<class_cnick> - The C nickname associated with the supplied class
-name.  If not supplied, will be derived if possible from C<class_name> by
-extracting the last class name component.
-
-=item * B<micro_sym> - The local identifier for the symbol.
-
-=back
-
-=head1 OBJECT METHODS
-
-=head2 get_parcel get_class_name get_class_cnick get_exposure micro_sym
-
-Getters.
-
-=head2 get_prefix get_Prefix get_PREFIX
-
-Get a string prefix, delegating to C<parcel> member var.
-
-=head2 public parcel private local
-
-    if    ( $sym->public ) { do_x() }
-    elsif ( $sym->parcel ) { do_y() }
-
-Indicate whether the symbol matches a given access level.
-
-=head2 equals
-
-    do_stuff() if $sym->equals($other_sym);
-
-Returns true if the symbols are "equal", false otherwise.
-
-=head2 short_sym
-
-    # e.g. "Lobster_average_lifespan"
-    print $symbol->short_sym;
-
-Returns the C representation for the symbol minus the parcel's prefix.
-
-=head2 full_sym
-
-    # e.g. "crust_Lobster_average_lifespan"
-    print $symbol->full_sym;
-
-Returns the fully qualified C representation for the symbol.
-
-=cut
-

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Type.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Type.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Type.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Type.pm Mon Dec 19 21:18:15 2011
@@ -18,327 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Type - A variable's type.
-
-=head1 METHODS
-
-=head2 new
-
-    my $type = MyType->new(
-        specifier   => 'char',    # default undef
-        indirection => undef,     # default 0
-        const       => 1,         # default undef
-        parcel      => undef,     # default undef
-        c_string    => undef,     # default undef
-    );
-
-Generic constructor.
-
-=over
-
-=item *
-
-B<specifier> - The C name for the type, not including any indirection or array
-subscripts.  
-
-=item *
-
-B<indirection> - integer indicating level of indirection. Example: the C type
-"float**" has a specifier of "float" and indirection 2.
-
-=item *
-
-B<const> - should be true if the type is const.
-
-=item *
-
-B<parcel> - A Clownfish::Parcel or a parcel name.
-
-=item *
-
-B<c_string> - The C representation of the type.
-
-=back
-
-=head2 new_integer
-
-    my $type = Clownfish::Type->new_integer(
-        const     => 1,       # default: undef
-        specifier => 'char',  # required
-    );
-
-Return a Type representing an integer primitive.
-
-Support is limited to a subset of the standard C integer types:
-
-    int8_t
-    int16_t
-    int32_t
-    int64_t
-    uint8_t
-    uint16_t
-    uint32_t
-    uint64_t
-    char
-    short
-    int
-    long
-    size_t
-
-Many others are not supported: "signed" or "unsigned" anything, "long long",
-"ptrdiff_t", "off_t", etc.  
-
-The following Charmonizer typedefs are supported:
-
-    bool_t
-
-=over
-
-=item * B<const> - Should be true if the type is const.
-
-=item * B<specifier> - Must match one of the supported types.
-
-=back
-
-=head2 new_float
-
-    my $type = Clownfish::Type->new_float(
-        const     => 1,           # default: undef
-        specifier => 'double',    # required
-    );
-
-Return a Type representing a floating point primitive.
-
-Two specifiers are supported:
-
-    float
-    double
-
-=over
-
-=item * B<const> - Should be true if the type is const.
-
-=item * B<specifier> - Must match one of the supported types.
-
-=back
-
-=cut
-
-=head2 new_composite
-
-    my $type = Clownfish::Type->new_composite(
-        child       => $char_type,    # required
-        indirection => undef,         # default 0
-        array       => '[]',          # default undef,
-        const       => 1,             # default undef
-    );
-
-Constructor for a composite type which is made up of repetitions of a single,
-uniform subtype.
-
-=over
-
-=item *
-
-B<child> - The Type which the composite is comprised of.
-
-=item *
-
-B<indirection> - integer indicating level of indirection. Example: the C type
-"float**" has indirection 2.
-
-=item *
-
-B<array> - A string describing an array postfix.  
-
-=item *
-
-B<const> - should be 1 if the type is const.
-
-=back
-
-=head2 new_object
-
-    my $type = Clownfish::Type->new_object(
-        specifier   => "Lobster",       # required
-        parcel      => "Crustacean",    # default: the default Parcel.
-        const       => undef,           # default undef
-        indirection => 1,               # default 1
-        incremented => 1,               # default 0
-        decremented => 0,               # default 0
-        nullable    => 1,               # default 0
-    );
-
-Create a Type representing an object.  The Type's C<specifier> must match the
-last component of the class name -- i.e. for the class "Crustacean::Lobster"
-it must be "Lobster".
-
-=over
-
-=item * B<specifier> - Required.  Must follow the rules for
-L<Clownfish::Class> class name components.
-
-=item * B<parcel> - A L<Clownfish::Parcel> or a parcel name.
-
-=item * B<const> - Should be true if the Type is const.  Note that this refers
-to the object itself and not the pointer.
-
-=item * B<indirection> - Level of indirection.  Must be 1 if supplied.
-
-=item * B<incremented> - Indicate whether the caller must take responsibility
-for an added refcount.
-
-=item * B<decremented> - Indicate whether the caller must account for
-for a refcount decrement.
-
-=item * B<nullable> - Indicate whether the object specified by this type may
-be NULL.
-
-=back
-
-The Parcel's prefix will be prepended to the specifier by new_object().
-
-=head2 new_void
-
-    my $type = Clownfish::Type->new_void(
-        specifier => 'void',    # default: void
-        const     => 1,         # default: undef
-    );
-
-Return a Type representing a the 'void' keyword in C.  It can be used either
-for a void return type, or in conjuction with with new_composite() to support
-the C<void*> opaque pointer type.
-
-=over
-
-=item * B<specifier> - Must be "void" if supplied.
-
-=item * B<const> - Should be true if the type is const.  (Useful in the
-context of C<const void*>).
-
-=back
-
-=head2 new_va_list
-
-    my $type = Clownfish::Type->new_va_list(
-        specifier => 'va_list',    # default: va_list
-    );
-
-Create a Type representing C's va_list, from stdarg.h.
-
-=over
-
-=item * B<specifier>.  Must be "va_list" if supplied.
-
-=back
-
-=head2 new_arbitrary
-
-    my $type = Clownfish::Type->new_arbitrary(
-        specifier => 'floatint_t',    # required
-        parcel    => 'Crustacean',    # default: undef
-    );
-
-"Arbitrary" types are a hack that spares us from having to support C types
-with complex declaration syntaxes -- such as unions, structs, enums, or
-function pointers -- from within Clownfish itself.
-
-The only constraint is that the C<specifier> must end in "_t".  This allows us
-to create complex types in a C header file...
-
-    typedef union { float f; int i; } floatint_t;
-
-... pound-include the C header, then use the resulting typedef in a Clownfish
-header file and have it parse as an "arbitrary" type.
-
-    floatint_t floatint;
-
-=over
-
-=item * B<specifier> - The name of the type, which must end in "_t".
-
-=item * B<parcel> - A L<Clownfish::Parcel> or a parcel name.
-
-=back
-
-If C<parcel> is supplied and C<specifier> begins with a capital letter, the
-Parcel's prefix will be prepended to the specifier:
-
-    foo_t         -> foo_t                # no prefix prepending
-    Lobster_foo_t -> crust_Lobster_foo_t  # prefix prepended
-
-=cut
-
-=head2 equals
-
-    do_stuff() if $type->equals($other);
-
-Returns true if two Clownfish::Type objects are equivalent.
-
-=head2 similar
-
-    do_stuff() if $type->similar($other_type);
-
-Weak checking of type which allows for covariant return types.  Calling this
-method on anything other than an object type is an error.
-
-=head2 to_c
-
-    # Declare variable "foo".
-    print $type->to_c . " foo;\n";
-
-Return the C representation of the type.
-
-=head2 set_c_string
-
-Set the C representation of the type.
-
-=head2 get_specifier get_parcel get_indirection get_array const nullable set_specifier set_nullable
-
-Accessors.
-
-=head2 is_object is_primitive is_integer is_floating is_composite is_void
-
-    do_stuff() if $type->is_object;
-
-Identify the flavor of Type, which is determined by the constructor which was
-used to create it.
-
-=over
-
-=item * is_object: Clownfish::Type->new_object
-
-=item * is_primitive: Either Clownfish::Type->new_integer or
-Clownfish::Type->new_float
-
-=item * is_integer: Clownfish::Type->new_integer
-
-=item * is_floating: Clownfish::Type->new_float
-
-=item * is_void: Clownfish::Type->new_void
-
-=item * is_composite: Clownfish::Type->new_composite
-
-=back
-
-=head2 is_string_type
-
-Returns true if $type represents a Clownfish type which holds unicode
-strings.
-
-=head2 incremented
-
-Returns true if the Type is incremented.  Only applicable to object Types.
-
-=head2 decremented
-
-Returns true if the Type is decremented.  Only applicable to object Types.
-
-=cut
-

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Util.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Util.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Util.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Util.pm Mon Dec 19 21:18:15 2011
@@ -18,56 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Util - Miscellaneous helper functions.
-
-=head1 DESCRIPTION
-
-Clownfish::Util provides a few convenience functions used internally by
-other Clownfish modules.
-
-=head1 FUNCTIONS
-
-=head2 slurp_text
-
-    my $foo_contents = slurp_text('foo.txt');
-
-Open a file, read it in (as text), return its contents.
-
-=head2 current
-
-    compile('foo.c') unless current( 'foo.c', 'foo.o' );
-
-Given two elements, which may be either scalars or arrays, verify that
-everything in the second group exists and was created later than anything in
-the first group.
-
-=head2 verify_args
-
-    verify_args( \%defaults, @_ ) or confess $@;
-
-Verify that named parameters exist in a defaults hash.  Returns false and sets
-$@ if a problem is detected.
-
-=head2 strip_c_comments
-
-    my $c_minus_comments = strip_c_comments($c_source_code);
-
-Quick 'n' dirty stripping of C comments.  Will massacre stuff like comments
-embedded in string literals, so watch out.
-
-=head2 write_if_changed
-
-    write_if_changed( $path, $content );
-
-Test whether there's a file at C<$path> which already matches C<$content>
-exactly.  If something has changed, write the file.  Otherwise do nothing (and
-avoid bumping the file's modification time).
-
-=cut
-

Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Variable.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Variable.pm?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Variable.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Variable.pm Mon Dec 19 21:18:15 2011
@@ -18,73 +18,3 @@ use Clownfish;
 
 1;
 
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Variable - A Clownfish variable.
-
-=head1 DESCRIPTION
-
-A variable, having a L<Type|Clownfish::Type>, a micro_sym (i.e. name), an
-exposure, and optionally, a location in the global namespace hierarchy.
-
-Variable objects which exist only within a local scope, e.g. those within
-parameter lists, do not need to know about class.  In contrast, inert class
-vars, for example, need to know class information so that they can declare
-themselves properly.
-
-=head1 METHODS
-
-=head2 new
-
-    my $var = Clownfish::Variable->new(
-        parcel      => 'Crustacean',
-        type        => $int32_t_type,            # required
-        micro_sym   => 'average_lifespan',       # required
-        exposure    => 'parcel',                 # default: 'local'
-        class_name  => "Crustacean::Lobster",    # default: undef
-        class_cnick => "Lobster",                # default: undef
-    );
-
-=over
-
-=item * B<type> - A L<Clownfish::Type>.
-
-=item * B<micro_sym> - The variable's name, without any namespacing prefixes.
-
-=item * B<exposure> - See L<Clownfish::Symbol>.
-
-=item * B<class_name> - See L<Clownfish::Symbol>.
-
-=item * B<class_cnick> - See L<Clownfish::Symbol>.
-
-=back
-
-=head2 local_c
-
-    # e.g. "int32_t average_lifespan"
-    print $variable->local_c;
-
-Returns a string with the Variable's C type and its C<micro_sym>.
-
-=head2 global_c
-
-    # e.g. "int32_t crust_Lobster_average_lifespan"
-    print $variable->global_c;
-
-Returns a string with the Variable's C type and its fully qualified name
-within the global namespace.
-
-=head2 local_declaration
-
-    # e.g. "int32_t average_lifespan;"
-    print $variable->local_declaration;
-
-Returns C code appropriate for declaring the variable in a local scope, such
-as within a struct definition, or as an automatic variable within a C
-function.  
-
-=cut

Modified: incubator/lucy/trunk/clownfish/src/CFCBase.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCBase.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCBase.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCBase.h Mon Dec 19 21:18:15 2011
@@ -17,6 +17,9 @@
 #ifndef H_CFCBASE
 #define H_CFCBASE
 
+/** Clownfish::Base - Base class for all CFC objects.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif

Modified: incubator/lucy/trunk/clownfish/src/CFCCBlock.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCCBlock.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCCBlock.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCCBlock.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,28 @@
  * limitations under the License.
  */
 
+/** Clownfish::CBlock - A block of embedded C code.
+ *
+ * CBlock exists to support embedding literal C code within Clownfish header
+ * files:
+ *
+ *     class Crustacean::Lobster {
+ *         ...
+ * 
+ *         inert inline void
+ *         say_hello(Lobster *self);
+ *     }
+ *
+ *     __C__
+ *     #include <stdio.h>
+ *     static CHY_INLINE void
+ *     crust_Lobster_say_hello(crust_Lobster *self)
+ *     {
+ *         printf("Prepare to die, human scum.\n");
+ *     }
+ *     __END_C__
+ */
+
 #ifndef H_CFCCBLOCK
 #define H_CFCCBLOCK
 
@@ -23,6 +45,10 @@ extern "C" {
 
 typedef struct CFCCBlock CFCCBlock;
 
+/** CBlock Constructor. 
+ *
+ * @param contents The contents of the CBlock, not including delimiters.
+ */
 CFCCBlock*
 CFCCBlock_new(const char *contents);
 
@@ -32,6 +58,8 @@ CFCCBlock_init(CFCCBlock *self, const ch
 void
 CFCCBlock_destroy(CFCCBlock *self);
 
+/** Accessor.
+ */
 const char*
 CFCCBlock_get_contents(CFCCBlock *self);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCClass.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCClass.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCClass.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCClass.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,12 @@
  * limitations under the License.
  */
 
+/** Clownfish::Class - An object representing a single class definition.
+ *
+ * Clownfish::Class objects are stored as quasi-singletons, one for each
+ * unique parcel/class_name combination.
+ */
+
 #ifndef H_CFCCLASS
 #define H_CFCCLASS
 
@@ -28,6 +34,25 @@ struct CFCFunction;
 struct CFCMethod;
 struct CFCVariable;
 
+/** Create and register a quasi-singleton.  May only be called once for each
+ * unique parcel/class_name combination.
+ *
+ * @param parcel See Clownfish::Symbol. 
+ * @param exposure See Clownfish::Symbol. 
+ * @param class_name See Clownfish::Symbol. 
+ * @param cnick See Clownfish::Symbol. 
+ * @param micro_sym Defaults to "class".
+ * @param docucomment An optional Clownfish::DocuComment attached to this class.
+ * @param source_class - The name of the class that owns the file in which
+ * this class was declared.  Should be "Foo" if "Foo::FooJr" is defined in
+ * <code>Foo.cfh</code>.
+ * @param parent_class_name - The name of this class's parent class.  Needed
+ * in order to establish the class hierarchy.
+ * @param docucomment A Clownfish::DocuComment describing this Class.
+ * @param is_inert Should be true if the class is inert, i.e. cannot be
+ * instantiated.
+ * @param is_final Should be true if the class is final.
+ */
 CFCClass*
 CFCClass_create(struct CFCParcel *parcel, const char *exposure,
                 const char *class_name, const char *cnick,
@@ -46,81 +71,138 @@ CFCClass_do_create(CFCClass *self, struc
 void
 CFCClass_destroy(CFCClass *self);
 
+/** Retrieve a Class, if one has already been created.
+ *
+ * @param A Clownfish::Parcel.
+ * @param class_name The name of the Class.
+ */
 CFCClass*
 CFCClass_fetch_singleton(struct CFCParcel *parcel, const char *class_name);
 
+/** Empty out the registry, decrementing the refcount of all Class singleton
+ * objects.
+ */
 void
 CFCClass_clear_registry(void);
 
+/** Add a child class.
+ */
 void
 CFCClass_add_child(CFCClass *self, CFCClass *child);
 
+/** Add a Function to the class.  Valid only before CFCClass_grow_tree() is
+ * called.
+ */
 void
 CFCClass_add_function(CFCClass *self, struct CFCFunction *func);
 
+/** Add a Method to the class.  Valid only before CFCClass_grow_tree() is
+ * called.
+ */
 void
 CFCClass_add_method(CFCClass *self, struct CFCMethod *method);
 
+/** Add a member variable to the class.  Valid only before
+ * CFCClass_grow_tree() is called.
+ */
 void
 CFCClass_add_member_var(CFCClass *self, struct CFCVariable *var);
 
+/** Add an inert (class) variable to the class.  Valid only before
+ * CFCClass_grow_tree() is called.
+ */
 void
 CFCClass_add_inert_var(CFCClass *self, struct CFCVariable *var);
 
+/** Add an arbitrary attribute to the class.
+ */
 void
 CFCClass_add_attribute(CFCClass *self, const char *name, const char *value);
 
+/** Returns true if the Class object has the supplied attribute, false
+ * otherwise.
+ */
 int
 CFCClass_has_attribute(CFCClass *self, const char *name);
 
+/* Return the inert Function object for the supplied sym, if any.
+ */
 struct CFCFunction*
 CFCClass_function(CFCClass *self, const char *sym);
 
+/* Return the Method object for the supplied micro/macro sym, if any.
+ */
 struct CFCMethod*
 CFCClass_method(CFCClass *self, const char *sym);
 
+/** Return a Method object if the Method corresponding to the supplied sym is
+ * novel.
+ */
 struct CFCMethod*
 CFCClass_novel_method(CFCClass *self, const char *sym);
 
+/** Bequeath all inherited methods and members to children.
+ */
 void
 CFCClass_grow_tree(CFCClass *self);
 
+/** Return this class and all its child classes as an array, where all
+ * children appear after their parent nodes.
+ */
 CFCClass**
 CFCClass_tree_to_ladder(CFCClass *self);
 
+/** Return an array of all novel methods.
+ */
 struct CFCMethod**
 CFCClass_novel_methods(CFCClass *self);
 
+/** Return an array of all novel member variables.
+ */
 struct CFCVariable**
 CFCClass_novel_member_vars(CFCClass *self);
 
+/** Return an array of all child classes.
+ */
 CFCClass**
 CFCClass_children(CFCClass *self);
 
+/** Return an array of all (inert) functions.
+ */
 struct CFCFunction**
 CFCClass_functions(CFCClass *self);
 
+/** Return an array of all methods.
+ */
 struct CFCMethod**
 CFCClass_methods(CFCClass *self);
 
 size_t
 CFCClass_num_methods(CFCClass *self);
 
+/** Return an array of all member variables.
+ */
 struct CFCVariable**
 CFCClass_member_vars(CFCClass *self);
 
+/** Return an array of all inert (shared, class) variables.
+ */
 struct CFCVariable**
 CFCClass_inert_vars(CFCClass *self);
 
 const char*
 CFCClass_get_cnick(CFCClass *self);
 
+/** Set the parent Class. (Not class name, Class.)
+ */
 void
 CFCClass_set_parent(CFCClass *self, CFCClass *parent);
 
 CFCClass*
 CFCClass_get_parent(CFCClass *self);
 
+/** Append auxiliary C code.
+ */
 void
 CFCClass_append_autocode(CFCClass *self, const char *autocode);
 
@@ -142,18 +224,30 @@ CFCClass_inert(CFCClass *self);
 const char*
 CFCClass_get_struct_sym(CFCClass *self);
 
+/** Fully qualified struct symbol, including the parcel prefix.
+ */
 const char*
 CFCClass_full_struct_sym(CFCClass *self);
 
+/** The short name of the global VTable object for this class.
+ */
 const char*
 CFCClass_short_vtable_var(CFCClass *self);
 
+/** Fully qualified vtable variable name, including the parcel prefix.
+ */
 const char*
 CFCClass_full_vtable_var(CFCClass *self);
 
 const char*
 CFCClass_full_vtable_hidden(CFCClass *self);
 
+/** The fully qualified C type specifier for this class's vtable, including
+ * the parcel prefix.  Each vtable needs to have its own type because each has
+ * a variable number of methods at the end of the struct, and it's not
+ * possible to initialize a static struct with a flexible array at the end
+ * under C89.
+ */
 const char*
 CFCClass_full_vtable_type(CFCClass *self);
 
@@ -163,6 +257,9 @@ CFCClass_full_vtable_type(CFCClass *self
 const char*
 CFCClass_privacy_symbol(CFCClass *self);
 
+/** Return a relative path to a C header file, appropriately formatted for a
+ * pound-include directive.
+ */
 const char*
 CFCClass_include_h(CFCClass *self);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCDocuComment.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCDocuComment.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCDocuComment.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCDocuComment.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+/** Clownfish::DocuComment - Formatted comment a la Doxygen.
+ */
+
 #ifndef H_CFCDOCUCOMMENT
 #define H_CFCDOCUCOMMENT
 
@@ -23,6 +26,8 @@ extern "C" {
 
 typedef struct CFCDocuComment CFCDocuComment;
 
+/** Parse comment text.
+ */
 CFCDocuComment*
 CFCDocuComment_parse(const char *raw_text);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCDumpable.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCDumpable.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCDumpable.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCDumpable.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,24 @@
  * limitations under the License.
  */
 
+/** Clownfish::Dumpable - Auto-generate code for "dumpable" classes.
+ *
+ * If a class declares that it has the attribute "dumpable", but does not
+ * declare either Dump or Load(), Clownfish::Dumpable will attempt to
+ * auto-generate those methods if methods inherited from the parent class do
+ * not suffice.
+ * 
+ *     class Foo::Bar inherits Foo : dumpable {
+ *         Thing *thing;
+ * 
+ *         public inert incremented Bar*
+ *         new();
+ * 
+ *         void
+ *         Destroy(Bar *self);
+ *     }
+ */
+
 #ifndef H_CFCDUMPABLE
 #define H_CFCDUMPABLE
 
@@ -24,6 +42,8 @@ extern "C" {
 typedef struct CFCDumpable CFCDumpable;
 struct CFCClass;
 
+/** Constructor. 
+ */
 CFCDumpable*
 CFCDumpable_new(void);
 
@@ -33,6 +53,10 @@ CFCDumpable_init(CFCDumpable *self);
 void
 CFCDumpable_destroy(CFCDumpable *self);
 
+
+/** Analyze a class with the attribute "dumpable" and add Dump() or Load()
+ * methods as necessary.
+ */
 void
 CFCDumpable_add_dumpables(CFCDumpable *self, struct CFCClass *klass);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCFile.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCFile.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCFile.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCFile.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,12 @@
  * limitations under the License.
  */
 
+
+/** Clownfish::File - Structured representation of the contents of a Clownfish
+ * source file.
+ * 
+ * An abstraction representing a file which contains Clownfish code.
+ */
 #ifndef H_CFCFILE
 #define H_CFCFILE
 
@@ -25,6 +31,13 @@ typedef struct CFCFile CFCFile;
 struct CFCBase;
 struct CFCClass;
 
+/**
+ * @param source_class The class name associated with the source file,
+ * regardless of how what classes are defined in the source file. Example: If
+ * source_class is "Foo::Bar", that implies that the source file could be
+ * found at 'Foo/Bar.cfh' within the source directory and that the output C
+ * header file should be 'Foo/Bar.h' within the target include directory.
+*/
 CFCFile*
 CFCFile_new(const char *source_class);
 
@@ -34,6 +47,9 @@ CFCFile_init(CFCFile *self, const char *
 void
 CFCFile_destroy(CFCFile *self);
 
+/** Add an element to the blocks array.  The block must be either a
+ * Clownfish::Class, a Clownfish::Parcel, or a Clownfish::CBlock.
+ */
 void
 CFCFile_add_block(CFCFile *self, CFCBase *block);
 
@@ -43,24 +59,37 @@ CFCFile_add_block(CFCFile *self, CFCBase
 size_t
 CFCFile_path_buf_size(CFCFile *self, const char *base_dir);
 
+/** Given a base directory, return a path name derived from the File's
+ * source_class with a ".c" extension.
+ */
 void
 CFCFile_c_path(CFCFile *self, char *buf, size_t buf_size,
                const char *base_dir);
 
+/** As c_path, but with a ".h" extension.
+ */
 void
 CFCFile_h_path(CFCFile *self, char *buf, size_t buf_size,
                const char *base_dir);
 
+/** As c_path, but with a ".cfh" extension.
+ */
 void
 CFCFile_cfh_path(CFCFile *self, char *buf, size_t buf_size,
                  const char *base_dir);
 
+/** Return all blocks as an array.
+ */
 struct CFCBase**
 CFCFile_blocks(CFCFile *self);
 
+/** Return all Clownfish::Class blocks from the file as an array.
+ */
 struct CFCClass**
 CFCFile_classes(CFCFile *self);
 
+/** Setter for the file's "modified" property, which is initially false.
+ */
 void
 CFCFile_set_modified(CFCFile *self, int modified);
 
@@ -70,12 +99,20 @@ CFCFile_get_modified(CFCFile *self);
 const char*
 CFCFile_get_source_class(CFCFile *self);
 
+/** Return a string used for an include guard in a C header (e.g.
+ * "H_CRUSTACEAN_LOBSTER"), unique per file.
+ */
 const char*
 CFCFile_guard_name(CFCFile *self);
 
+/** Return a string opening the include guard.
+ */
 const char*
 CFCFile_guard_start(CFCFile *self);
 
+/** Return a string closing the include guard.  Other classes count on being
+ * able to match this string.
+ */
 const char*
 CFCFile_guard_close(CFCFile *self);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCFunction.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCFunction.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCFunction.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCFunction.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+/** Clownfish::Function - Metadata describing a function.
+ */
+
 #ifndef H_CFCFUNCTION
 #define H_CFCFUNCTION
 
@@ -39,7 +42,23 @@ struct CFCFunction {
 };
 #endif
 
-
+/**
+ * @param parcel A Clownfish::Parcel.
+ * @param exposure The function's exposure (see L<Clownfish::Symbol>).
+ * @param class_name The full name of the class in whose namespace the
+ * function resides.
+ * @param class_cnick The C nickname for the class. 
+ * @param micro_sym The lower case name of the function, without any
+ * namespacing prefixes.
+ * @param return_type A Clownfish::Type representing the function's
+ * return type.
+ * @param param_list A Clownfish::ParamList representing the
+ * function's argument list.
+ * @param docucomment A Clownfish::DocuComment describing the
+ * function.
+ * @param is_inline Should be true if the function should be inlined by the
+ * compiler.
+ */
 CFCFunction*
 CFCFunction_new(struct CFCParcel *parcel, const char *exposure,
                 const char *class_name, const char *class_cnick,
@@ -69,12 +88,18 @@ CFCFunction_get_docucomment(CFCFunction 
 int
 CFCFunction_inline(CFCFunction *self);
 
+/** Returns true if the function has a void return type, false otherwise.
+ */
 int
 CFCFunction_void(CFCFunction *self);
 
+/** A synonym for full_sym().
+ */
 const char*
 CFCFunction_full_func_sym(CFCFunction *self);
 
+/** A synonym for short_sym().
+ */
 const char*
 CFCFunction_short_func_sym(CFCFunction *self);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCHierarchy.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCHierarchy.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCHierarchy.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCHierarchy.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,16 @@
  * limitations under the License.
  */
 
+/** Clownfish::Hierarchy - A class hierarchy.
+ *
+ * A Clownfish::Hierarchy consists of all the classes defined in files within
+ * a source directory and its subdirectories.
+ *
+ * There may be more than one tree within the Hierarchy, since all "inert"
+ * classes are root nodes, and since Clownfish does not officially define any
+ * core classes itself from which all instantiable classes must descend.
+ */
+
 #ifndef H_CFCHIERARCHY
 #define H_CFCHIERARCHY
 
@@ -25,6 +35,10 @@ typedef struct CFCHierarchy CFCHierarchy
 struct CFCClass;
 struct CFCFile;
 
+/**
+ * @param source The directory we begin reading files from.
+ * @param dest The directory where the autogenerated files will be written.
+ */
 CFCHierarchy*
 CFCHierarchy_new(const char *source, const char *dest);
 
@@ -34,12 +48,23 @@ CFCHierarchy_init(CFCHierarchy *self, co
 void
 CFCHierarchy_destroy(CFCHierarchy *self);
 
+/** Parse every Clownfish header file which can be found under C<source>,
+ * building up the object hierarchy.
+ */
 void
 CFCHierarchy_build(CFCHierarchy *self);
 
+/** Visit all File objects in the hierarchy.  If a parent node is modified, mark
+ * all of its children as modified.  
+ *
+ * If the supplied argument is true, mark all Files as modified.
+ */
 int
 CFCHierarchy_propagate_modified(CFCHierarchy *self, int modified);
 
+/** Return all Classes as an array with the property that every parent class
+ * will precede all of its children.
+ */
 struct CFCClass**
 CFCHierarchy_ordered_classes(CFCHierarchy *self);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCMethod.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCMethod.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCMethod.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCMethod.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,16 @@
  * limitations under the License.
  */
 
+/** Clownfish::Method - Metadata describing an instance method.
+ *
+ * Clownfish::Method is a specialized subclass of Clownfish::Function, with
+ * the first argument required to be an Obj.
+ *
+ * When compiling Clownfish code to C, Method objects generate all the code
+ * that Function objects do, but also create symbols for indirect invocation via
+ * VTable.
+ */
+
 #ifndef H_CFCMETHOD
 #define H_CFCMETHOD
 
@@ -27,6 +37,21 @@ struct CFCType;
 struct CFCParamList;
 struct CFCDocuComment;
 
+/**
+ * @param parcel See Clownfish::Function.
+ * @param exposure See Clownfish::Function.  Defaults to "parcel" if not
+ * supplied.
+ * @param class_name See Clownfish::Function.
+ * @param class_cnick See Clownfish::Function.
+ * @param macro_sym - The mixed case name which will be used when invoking the
+ * method.
+ * @param return_type See Clownfish::Function.
+ * @param param_list - A Clownfish::ParamList.  The first element must be an
+ * object of the class identified by C<class_name>.
+ * @param docucomment see Clownfish::Function.  May be NULL.
+ * @param is_final - Indicate whether the method is final.
+ * @param is_abstract - Indicate whether the method is abstract.
+ */
 CFCMethod*
 CFCMethod_new(struct CFCParcel *parcel, const char *exposure,
               const char *class_name, const char *class_cnick,
@@ -46,16 +71,41 @@ CFCMethod_init(CFCMethod *self, struct C
 void
 CFCMethod_destroy(CFCMethod *self);
 
+/** Returns true if the methods have signatures and attributes which allow one
+ * to override the other.
+ */
 int
 CFCMethod_compatible(CFCMethod *self, CFCMethod *other);
 
+/** Let the Method know that it is overriding a method which was defined in a
+ * parent class, and verify that the override is valid.
+ *
+ * All methods start out believing that they are "novel", because we don't
+ * know about inheritance until we build the hierarchy after all files have
+ * been parsed.  override() is a way of going back and relabeling a method as
+ * overridden when new information has become available: in this case, that a
+ * parent class has defined a method with the same name.
+ */
 void
 CFCMethod_override(CFCMethod *self, CFCMethod *orig);
 
+/** As with override, above, this is for going back and changing the nature of
+ * a Method after new information has become available -- typically, when we
+ * discover that the method has been inherited by a "final" class.
+ *
+ * However, we don't modify the original Method as with override().  Inherited
+ * Method objects are shared between parent and child classes; if a shared
+ * Method object were to become final, it would interfere with its own
+ * inheritance.  So, we make a copy, slightly modified to indicate that it is
+ * "final".  
+ */
 CFCMethod*
 CFCMethod_finalize(CFCMethod *self);
 
 /**
+ * Create the symbol used to invoke the method without the parcel Prefix, e.g.
+ * "LobClaw_Pinch".
+ *
  * @return the number of bytes which the symbol would occupy.
  */
 size_t
@@ -63,13 +113,18 @@ CFCMethod_short_method_sym(CFCMethod *se
                            size_t buf_size);
 
 /**
+ * Create the fully-qualified symbol used to invoke the method, e.g.
+ * "Crust_LobClaw_Pinch".
+ *
  * @return the number of bytes which the symbol would occupy.
  */
 size_t
 CFCMethod_full_method_sym(CFCMethod *self, const char *invoker, char *buf,
                           size_t buf_size);
 
-/**
+/** Create the fully qualified name of the variable which stores the method's
+ * vtable offset, e.g. "crust_LobClaw_pinch_OFFSET".
+ *
  * @return the number of bytes which the symbol would occupy.
  */
 size_t
@@ -82,15 +137,29 @@ CFCMethod_get_macro_sym(CFCMethod *self)
 const char*
 CFCMethod_micro_sym(CFCMethod *self);
 
+/** Returns the typedef symbol for this method, which is derived from the
+ * class nick of the first class in which the method was declared, e.g.
+ * "Claw_pinch_t".
+ */
 const char*
 CFCMethod_short_typedef(CFCMethod *self);
 
+/** Returns the fully-qualified typedef symbol including parcel prefix, e.g.
+ * "crust_Claw_pinch_t".
+ */
 const char*
 CFCMethod_full_typedef(CFCMethod *self);
 
+/** Returns the fully qualified name of the variable which stores the method's
+ * Callback object, e.g. "crust_LobClaw_pinch_CALLBACK".
+ */
 const char*
 CFCMethod_full_callback_sym(CFCMethod *self);
 
+/** Returns the fully qualified name of the function which implements the
+ * callback to the host in the event that a host method has been defined which
+ * overrides this method, e.g. "crust_LobClaw_pinch_OVERRIDE".
+ */
 const char*
 CFCMethod_full_override_sym(CFCMethod *self);
 
@@ -100,9 +169,16 @@ CFCMethod_final(CFCMethod *self);
 int
 CFCMethod_abstract(CFCMethod *self);
 
+/** Returns true if the method's class is the first in the inheritance
+ * hierarchy in which the method was declared -- i.e. the method is neither
+ * inherited nor overridden.
+ */
 int
 CFCMethod_novel(CFCMethod *self);
 
+/** Return the Clownfish::Type for <code>self</code>.
+ */
+
 struct CFCType*
 CFCMethod_self_type(CFCMethod *self);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCParamList.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCParamList.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCParamList.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCParamList.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+/** Clownfish::ParamList - parameter list.
+ */
+
 #ifndef H_CFCPARAMLIST
 #define H_CFCPARAMLIST
 
@@ -24,6 +27,9 @@ extern "C" {
 typedef struct CFCParamList CFCParamList;
 struct CFCVariable;
 
+/**
+ * @param variadic Should be true if the function is variadic.
+ */
 CFCParamList*
 CFCParamList_new(int variadic);
 
@@ -33,6 +39,12 @@ CFCParamList_init(CFCParamList *self, in
 void
 CFCParamList_destroy(CFCParamList *self);
 
+/** Add a parameter to the ParamList.
+ * 
+ * @param variable A Clownfish::Variable.
+ * @param value The parameter's default value, which should be NULL
+ * if there is no default and thus the parameter is required.
+ */
 void
 CFCParamList_add_param(CFCParamList *self, struct CFCVariable *variable,
                        const char *value);
@@ -49,12 +61,25 @@ CFCParamList_set_variadic(CFCParamList *
 int
 CFCParamList_variadic(CFCParamList *self);
 
+/** Return the number of variables in the ParamList, including "self" for
+ * methods.
+ */
 size_t
 CFCParamList_num_vars(CFCParamList *self);
 
+
+/** Return a list of the variable's types and names, joined by commas.  For
+ * example:
+ *
+ *     Obj* self, Foo* foo, Bar* bar
+ */
 const char*
 CFCParamList_to_c(CFCParamList *self);
 
+/** Return the variable's names, joined by commas.  For example:
+ * 
+ *     self, foo, bar
+ */
 const char*
 CFCParamList_name_list(CFCParamList *self);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCParcel.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCParcel.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCParcel.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCParcel.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,21 @@
  * limitations under the License.
  */
 
+/** Clownfish::Parcel - Collection of code.
+ *
+ * A Parcel is a cohesive collection of code, which could, in theory, be
+ * published as as a single entity.
+ *
+ * Clownfish supports two-tier manual namespacing, using a prefix, an optional
+ * class nickname, and the local symbol:
+ * 
+ *     prefix_ClassNick_local_symbol
+ * 
+ * Clownfish::Parcel supports the first tier, specifying initial prefixes.
+ * These prefixes come in three capitalization variants: prefix_, Prefix_, and
+ * PREFIX_.
+ */
+
 #ifndef H_CFCPARCEL
 #define H_CFCPARCEL
 
@@ -23,6 +38,14 @@ extern "C" {
 
 typedef struct CFCParcel CFCParcel;
 
+/** Add a Parcel singleton to a global registry.  May be called multiple times,
+ * but only with compatible arguments.
+ *
+ * @param name The name of the parcel.
+ * @param cnick The C nickname for the parcel, which will be used as a prefix
+ * for generated global symbols.  Must be mixed case and start with a capital
+ * letter.  Defaults to <code>name</code>
+ */
 CFCParcel*
 CFCParcel_singleton(const char *name, const char *cnick);
 
@@ -40,6 +63,8 @@ CFCParcel_init(CFCParcel *self, const ch
 void
 CFCParcel_destroy(CFCParcel *self);
 
+/** Return the singleton for default parcel, which has no prefix.
+ */
 CFCParcel*
 CFCParcel_default_parcel(void);
 
@@ -59,12 +84,18 @@ CFCParcel_get_name(CFCParcel *self);
 const char*
 CFCParcel_get_cnick(CFCParcel *self);
 
+/** Return the all-lowercase version of the Parcel's prefix.
+ */
 const char*
 CFCParcel_get_prefix(CFCParcel *self);
 
+/** Return the Titlecase version of the Parcel's prefix.
+ */
 const char*
 CFCParcel_get_Prefix(CFCParcel *self);
 
+/** Return the all-caps version of the Parcel's prefix.
+ */
 const char*
 CFCParcel_get_PREFIX(CFCParcel *self);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCParser.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCParser.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCParser.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCParser.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,13 @@
  * limitations under the License.
  */
 
+/** Clownfish::Parser - Parse Clownfish header files.
+ *
+ * Clownfish::Parser is a combined lexer/parser which parses Clownfish header
+ * files.  It is not at all strict, as it relies heavily on the C parser to
+ * pick up errors such as misspelled type names.  
+ */
+
 #ifndef H_CFCPARSER
 #define H_CFCPARSER
 

Modified: incubator/lucy/trunk/clownfish/src/CFCSymbol.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCSymbol.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCSymbol.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCSymbol.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,12 @@
  * limitations under the License.
  */
 
+/** Clownfish::Symbol - Base class for Clownfish symbols.
+ *
+ * Clownfish::Symbol serves as a parent class for entities which may live in
+ * the global namespace, such as classes, functions, methods, and variables.
+ */
+
 #ifndef H_CFCSYMBOL
 #define H_CFCSYMBOL
 
@@ -46,6 +52,20 @@ struct CFCSymbol {
 int
 CFCSymbol_validate_class_name_component(const char *name);
 
+/**
+ * @param parcel A Clownfish::Parcel.  If not supplied, will be assigned to the
+ * default Parcel.
+ * @param exposure The scope in which the symbol is exposed.  Must be
+ * 'public', 'parcel', 'private', or 'local'.
+ * @param class_name A optional class name, consisting of one or more
+ * components separated by "::".  Each component must start with a capital
+ * letter, contain at least one lower-case letter, and consist entirely of the
+ * characters [A-Za-z0-9].
+ * @param class_cnick The C nickname associated with the supplied class
+ * name.  If not supplied, will be derived if possible from C<class_name> by
+ * extracting the last class name component.
+ * @param micro_sym The local identifier for the symbol.
+ */
 CFCSymbol*
 CFCSymbol_new(struct CFCParcel *parcel, const char *exposure, const char *class_name,
               const char *class_cnick, const char *micro_sym);
@@ -58,6 +78,8 @@ CFCSymbol_init(CFCSymbol *self, struct C
 void
 CFCSymbol_destroy(CFCSymbol *self);
 
+/** Return true if the symbols are "equal", false otherwise.
+ */
 int
 CFCSymbol_equals(CFCSymbol *self, CFCSymbol *other);
 
@@ -75,33 +97,55 @@ CFCSymbol_get_class_cnick(CFCSymbol *sel
 const char*
 CFCSymbol_get_exposure(CFCSymbol *self);
 
+/** Return true if the Symbol's exposure is "public".
+ */
 int
 CFCSymbol_public(CFCSymbol *self);
 
+/** Return true if the Symbol's exposure is "parcel".
+ */
 int
 CFCSymbol_parcel(CFCSymbol *self);
 
+/** Return true if the Symbol's exposure is "private".
+ */
 int
 CFCSymbol_private(CFCSymbol *self);
 
+/** Return true if the Symbol's exposure is "local".
+ */
 int
 CFCSymbol_local(CFCSymbol *self);
 
+/** Accessor for the Symbol's micro_sym.
+ */
 const char*
 CFCSymbol_micro_sym(CFCSymbol *self);
 
+/** Returns the C representation for the symbol minus the parcel's prefix,
+ * e.g.  "Lobster_average_lifespan".
+ */
 const char*
 CFCSymbol_short_sym(CFCSymbol *self);
 
+/** Returns the fully qualified C representation for the symbol, e.g.
+ * "crust_Lobster_average_lifespan".
+ */
 const char*
 CFCSymbol_full_sym(CFCSymbol *self);
 
+/** Get the Symbol's all-lowercase prefix, delegating to <code>parcel</code>.
+ */
 const char*
 CFCSymbol_get_prefix(CFCSymbol *self);
 
+/** Get the Symbol's Titlecase prefix, delegating to <code>parcel</code>.
+ */
 const char*
 CFCSymbol_get_Prefix(CFCSymbol *self);
 
+/** Get the Symbol's all-uppercase prefix, delegating to <code>parcel</code>.
+ */
 const char*
 CFCSymbol_get_PREFIX(CFCSymbol *self);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCType.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCType.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCType.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCType.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 
+/** Clownfish::Type - A variable's type.
+ */
+
 #ifndef H_CFCTYPE
 #define H_CFCTYPE
 
@@ -38,6 +41,17 @@ struct CFCParcel;
 #define CFCTYPE_ARBITRARY   0x00000800
 #define CFCTYPE_COMPOSITE   0x00001000
 
+/** Generic constructor.
+ * 
+ * @param flags Flags which apply to the Type.  Supplying incompatible flags
+ * will trigger an error.
+ * @param parcel A Clownfish::Parcel.
+ * @param specifier The C name for the type, not including any indirection or
+ * array subscripts.  
+ * @param indirection integer indicating level of indirection. Example: the C
+ * type "float**" has a specifier of "float" and indirection 2.
+ * @param c_string The C representation of the type.
+ */
 CFCType*
 CFCType_new(int flags, struct CFCParcel *parcel, const char *specifier,
             int indirection, const char *c_string);
@@ -46,35 +60,147 @@ CFCType*
 CFCType_init(CFCType *self, int flags, struct CFCParcel *parcel,
              const char *specifier, int indirection, const char *c_string);
 
+    my $type = Clownfish::Type->new_integer(
+        const     => 1,       # default: undef
+        specifier => 'char',  # required
+    );
+
+/** Return a Type representing an integer primitive.
+ *
+ * Support is limited to a subset of the standard C integer types:
+ *
+ *     int8_t
+ *     int16_t
+ *     int32_t
+ *     int64_t
+ *     uint8_t
+ *     uint16_t
+ *     uint32_t
+ *     uint64_t
+ *     char
+ *     short
+ *     int
+ *     long
+ *     size_t
+ *
+ * Many others are not supported: "signed" or "unsigned" anything, "long
+ * long", "ptrdiff_t", "off_t", etc.  
+ *
+ * The following Charmonizer typedefs are supported:
+ *
+ *     bool_t
+ *
+ * @param flags Allowed flags: CONST, INTEGER, PRIMITIVE.
+ * @param specifier Must match one of the supported types.
+ */
 CFCType*
 CFCType_new_integer(int flags, const char *specifier);
 
+/** Return a Type representing a floating point primitive.
+ *
+ * @param flags Allowed flags: CONST, FLOATING, PRIMITIVE.
+ * @param specifier Must be either 'float' or 'double'.
+ */
 CFCType*
 CFCType_new_float(int flags, const char *specifier);
 
+
+=head2 new_object
+
+    my $type = Clownfish::Type->new_object(
+        specifier   => "Lobster",       # required
+        parcel      => "Crustacean",    # default: the default Parcel.
+        const       => undef,           # default undef
+        indirection => 1,               # default 1
+        incremented => 1,               # default 0
+        decremented => 0,               # default 0
+        nullable    => 1,               # default 0
+    );
+
+/** Create a Type representing an object.
+ *
+ * The supplied <code>specifier</code> must match the last component of the
+ * class name -- i.e. for the class "Crustacean::Lobster" it must be
+ * "Lobster".
+ *
+ * The Parcel's prefix will be prepended to the specifier by new_object().
+ *
+ * @param flags Allowed flags: OBJECT, STRING_TYPE, CONST, NULLABLE,
+ * INCREMENTED, DECREMENTED.
+ * @param parcel A Clownfish::Parcel.
+ * @param specifier Required.  Must follow the rules for Clownfish::Class
+ * class name components.
+ * @param indirection Level of indirection.  Must be 1 if supplied.
+ */
 CFCType*
 CFCType_new_object(int flags, struct CFCParcel *parcel, const char *specifier,
                    int indirection);
 
+/** Constructor for a composite type which is made up of repetitions of a
+ * single, uniform subtype.
+ *
+ * @param flags Allowed flags: COMPOSITE, NULLABLE
+ * @param child The Clownfish::Type which the composite is comprised of.
+ * @param indirection integer indicating level of indirection. Example: the C type
+ * "float**" has indirection 2.
+ * @param array A string describing an array postfix.  
+ */
 CFCType*
 CFCType_new_composite(int flags, CFCType *child, int indirection,
                       const char *array);
 
+/** Return a Clownfish::Type representing a the 'void' keyword in C.  It can
+ * be used either for a void return type, or in conjuction with with
+ * new_composite() to support the <code>void*</code> opaque pointer type.
+ *
+ * @param is_const Should be true if the type is const.  (Useful in the
+ * context of <code>const void*</code>).
+ */
 CFCType*
 CFCType_new_void(int is_const);
 
+/** Create a Type representing C's va_list, from stdarg.h.
+ */
 CFCType*
 CFCType_new_va_list(void);
 
+/** "Arbitrary" types are a hack that spares us from having to support C types
+ * with complex declaration syntaxes -- such as unions, structs, enums, or
+ * function pointers -- from within Clownfish itself.
+ *
+ * The only constraint is that the <code>specifier</code> must end in "_t".
+ * This allows us to create complex types in a C header file...
+ *
+ *    typedef union { float f; int i; } floatint_t;
+ *
+ * ... pound-include the C header, then use the resulting typedef in a
+ * Clownfish header file and have it parse as an "arbitrary" type.
+ *
+ *    floatint_t floatint;
+ *
+ * If <code>parcel</code> is supplied and <code>specifier</code> begins with a
+ * capital letter, the Parcel's prefix will be prepended to the specifier:
+ *
+ *    foo_t         -> foo_t                # no prefix prepending
+ *    Lobster_foo_t -> crust_Lobster_foo_t  # prefix prepended
+ *
+ * @param specifier The name of the type, which must end in "_t".
+ * @param parcel A Clownfish::Parcel.
+ */
 CFCType*
 CFCType_new_arbitrary(struct CFCParcel *parcel, const char *specifier);
 
 void
 CFCType_destroy(CFCType *self);
 
+/** Returns true if two Clownfish::Type objects are equivalent.
+ */
 int
 CFCType_equals(CFCType *self, CFCType *other);
 
+/** Weak checking of type which allows for covariant return types.  Calling
+ * this method on anything other than an object type is an error.
+ */
 int
 CFCType_similar(CFCType *self, CFCType *other);
 
@@ -96,9 +222,13 @@ CFCType_get_indirection(CFCType *self);
 struct CFCParcel*
 CFCType_get_parcel(CFCType *self);
 
+/** Set the C representation of the Type.
+ */
 void
 CFCType_set_c_string(CFCType *self, const char *c_string);
 
+/** Return the C representation of the type.
+ */
 const char*
 CFCType_to_c(CFCType *self);
 
@@ -117,9 +247,13 @@ CFCType_set_nullable(CFCType *self, int 
 int
 CFCType_nullable(CFCType *self);
 
+/** Returns true if the Type is incremented.  Only applicable to object Types.
+ */
 int
 CFCType_incremented(CFCType *self);
 
+/** Returns true if the Type is decremented.  Only applicable to object Types.
+ */
 int
 CFCType_decremented(CFCType *self);
 
@@ -138,6 +272,9 @@ CFCType_is_integer(CFCType *self);
 int
 CFCType_is_floating(CFCType *self);
 
+/** Returns true if $type represents a Clownfish type which holds unicode
+ * strings.
+ */
 int
 CFCType_is_string_type(CFCType *self);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCUtil.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCUtil.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCUtil.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCUtil.h Mon Dec 19 21:18:15 2011
@@ -14,6 +14,12 @@
  * limitations under the License.
  */
 
+/** Clownfish::Util - Miscellaneous helper functions.
+ *
+ * Clownfish::Util provides a few convenience functions used internally by
+ * other Clownfish modules.
+ */
+
 #ifndef H_CFCUTIL
 #define H_CFCUTIL
 
@@ -91,6 +97,9 @@ CFCUtil_wrapped_free(void *ptr);
 #define FREEMEM(_ptr) \
     CFCUtil_wrapped_free(_ptr)
 
+/** Given two filepaths, return true if the second exists and has a
+ * modification time which more recent than that of the first. 
+ */
 int
 CFCUtil_current(const char *orig, const char *dest);
 
@@ -100,6 +109,10 @@ CFCUtil_current(const char *orig, const 
 void
 CFCUtil_write_file(const char *filename, const char *content, size_t len);
 
+/** Test whether there's a file at <code>path</code> which already matches
+ * <code>content</code> exactly.  If something has changed, write the file.
+ * Otherwise do nothing (and avoid bumping the file's modification time).
+ */
 void
 CFCUtil_write_if_changed(const char *path, const char *content, size_t len);
 

Modified: incubator/lucy/trunk/clownfish/src/CFCVariable.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCVariable.h?rev=1220952&r1=1220951&r2=1220952&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCVariable.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCVariable.h Mon Dec 19 21:18:15 2011
@@ -17,6 +17,17 @@
 #ifndef H_CFCVARIABLE
 #define H_CFCVARIABLE
 
+/** Clownfish::Variable - A Clownfish variable.
+ *
+ * A variable, having a L<Type|Clownfish::Type>, a micro_sym (i.e. name), an
+ * exposure, and optionally, a location in the global namespace hierarchy.
+ *
+ * Variable objects which exist only within a local scope, e.g. those within
+ * parameter lists, do not need to know about class.  In contrast, inert class
+ * vars, for example, need to know class information so that they can declare
+ * themselves properly.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -25,6 +36,22 @@ typedef struct CFCVariable CFCVariable;
 struct CFCParcel;
 struct CFCType;
 
+    my $var = Clownfish::Variable->new(
+        parcel      => 'Crustacean',
+        type        => $int32_t_type,            # required
+        micro_sym   => 'average_lifespan',       # required
+        exposure    => 'parcel',                 # default: 'local'
+        class_name  => "Crustacean::Lobster",    # default: undef
+        class_cnick => "Lobster",                # default: undef
+    );
+
+/** 
+ * @param type A Clownfish::Type.
+ * @param micro_sym The variable's name, without any namespacing prefixes.
+ * @param exposure See Clownfish::Symbol.
+ * @param class_name See Clownfish::Symbol.
+ * @param class_cnick See Clownfish::Symbol.
+ */
 CFCVariable*
 CFCVariable_new(struct CFCParcel *parcel, const char *exposure,
                 const char *class_name, const char *class_cnick,
@@ -48,12 +75,29 @@ CFCVariable_get_type(CFCVariable *self);
 int
 CFCVariable_inert(CFCVariable *self);
 
+
+/** Returns a string with the Variable's C type and its
+ * <code>micro_sym</code>. For instance:
+ *
+ *     int32_t average_lifespan
+ */
 const char*
 CFCVariable_local_c(CFCVariable *self);
 
+/** Returns a string with the Variable's C type and its fully qualified name
+ * within the global namespace.  For example:
+ *
+ *     int32_t crust_Lobster_average_lifespan
+ */
 const char*
 CFCVariable_global_c(CFCVariable *self);
 
+/** Returns C code appropriate for declaring the variable in a local scope, such
+ * as within a struct definition, or as an automatic variable within a C
+ * function.  For example:
+ *
+ *     int32_t average_lifespan;
+ */
 const char*
 CFCVariable_local_declaration(CFCVariable *self);