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/20 03:19:34 UTC
[lucy-commits] svn commit: r1221074 - in /incubator/lucy/trunk/clownfish:
perl/lib/Clownfish/Binding/ perl/lib/Clownfish/Binding/Core/ src/
Author: marvin
Date: Tue Dec 20 02:19:34 2011
New Revision: 1221074
URL: http://svn.apache.org/viewvc?rev=1221074&view=rev
Log:
Move docs for CFC core bindings to .h files.
Modified:
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core.pm
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Class.pm
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/File.pm
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Function.pm
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Method.pm
incubator/lucy/trunk/clownfish/src/CFCBindClass.h
incubator/lucy/trunk/clownfish/src/CFCBindCore.h
incubator/lucy/trunk/clownfish/src/CFCBindFile.h
incubator/lucy/trunk/clownfish/src/CFCBindFunction.h
incubator/lucy/trunk/clownfish/src/CFCBindMethod.h
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core.pm?rev=1221074&r1=1221073&r2=1221074&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core.pm Tue Dec 20 02:19:34 2011
@@ -18,65 +18,3 @@ use Clownfish;
1;
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Binding::Core - Generate core C code for a Clownfish::Hierarchy.
-
-=head1 SYNOPSIS
-
- my $hierarchy = Clownfish::Hierarchy->new(
- source => '/path/to/clownfish/files',
- dest => 'autogen',
- );
- $hierarchy->build;
- my $core_binding = Clownfish::Binding::Core->new(
- hierarchy => $hierarchy,
- dest => 'autogen',
- header => "/* Auto-generated file. */\n",
- footer => $copyfoot,
- );
- my $modified = $core_binding->write_all_modified($modified);
-
-=head1 DESCRIPTION
-
-A Clownfish::Hierarchy describes an abstract specifiction for a class
-hierarchy; Clownfish::Binding::Core is responsible for auto-generating C
-code which implements that specification.
-
-=head1 METHODS
-
-=head2 new
-
- my $binding = Clownfish::Binding::Core->new(
- hierarchy => $hierarchy, # required
- dest => '/path/to/autogen', # required
- header => $header, # required
- footer => $footer, # required
- );
-
-=over
-
-=item * B<hierarchy> - A L<Clownfish::Hierarchy>.
-
-=item * B<dest> - The directory where C output files will be written.
-
-=item * B<header> - Text which will be prepended to each generated C file --
-typically, an "autogenerated file" warning.
-
-=item * B<footer> - Text to be appended to the end of each generated C file --
-typically copyright information.
-
-=back
-
-=head2 write_all_modified
-
-Call C<< $hierarchy->propagate_modified >> to establish which classes do not
-have up-to-date generated .c and .h files, then traverse the hierarchy writing
-all necessary files.
-
-=cut
-
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Class.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Class.pm?rev=1221074&r1=1221073&r2=1221074&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Class.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Class.pm Tue Dec 20 02:19:34 2011
@@ -18,41 +18,3 @@ use Clownfish;
1;
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Binding::Core::Class - Generate core C code for a class.
-
-=head1 DESCRIPTION
-
-Clownfish::Class is an abstract specification for a class. This module
-autogenerates the C code with implements that specification.
-
-=head1 METHODS
-
-=head2 new
-
- my $class_binding = Clownfish::Binding::Core::Class->new(
- client => $class,
- );
-
-=over
-
-=item * B<client> - A L<Clownfish::Class>.
-
-=back
-
-=head2 to_c_header
-
-Return the .h file which contains autogenerated C code defining the class's
-interface: all method invocation functions, etc...
-
-=head2 to_c
-
-Return the .c file which contains autogenerated C code necessary for the class
-to function properly.
-
-=cut
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/File.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/File.pm?rev=1221074&r1=1221073&r2=1221074&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/File.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/File.pm Tue Dec 20 02:19:34 2011
@@ -18,51 +18,4 @@ use Clownfish;
1;
-__END__
-__POD__
-
-=head1 NAME
-
-Clownfish::Binding::Core::File - Generate core C code for a Clownfish file.
-
-=head1 DESCRIPTION
-
-This module is the companion to Clownfish::File, generating the C code
-needed to implement the file's specification.
-
-There is a one-to-one mapping between Clownfish header files and autogenerated
-.h and .c files. If Foo.cfh includes both Foo and Foo::FooJr, then it is
-necessary to pound-include "Foo.h" in order to get FooJr's interface -- not
-"Foo/FooJr.h", which won't exist.
-
-=head1 CLASS METHODS
-
-=head2 write_h
-
- Clownfish::Binding::Core::File->write_c(
- file => $file, # required
- dest => '/path/to/autogen_dir', # required
- header => "/* Autogenerated file. */\n", # required
- footer => $copyfoot, # required
- );
-
-Generate a C header file containing all class declarations and literal C
-blocks.
-
-=over
-
-=item * B<file> - A L<Clownfish::File>.
-
-=item * B<dest> - The directory under which autogenerated files are being
-written.
-
-=item * B<header> - Text which will be prepended to each generated C file --
-typically, an "autogenerated file" warning.
-
-=item * B<footer> - Text to be appended to the end of each generated C file --
-typically copyright information.
-
-=back
-
-=cut
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Function.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Function.pm?rev=1221074&r1=1221073&r2=1221074&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Function.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Function.pm Tue Dec 20 02:19:34 2011
@@ -18,21 +18,3 @@ use Clownfish;
1;
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Binding::Core::Function - Generate core C code for a function.
-
-=head1 CLASS METHODS
-
-=head2 func_declaration
-
- my $declaration
- = Clownfish::Binding::Core::Function->func_declaration($function);
-
-Return C code declaring the function's C implementation.
-
-=cut
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Method.pm
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Method.pm?rev=1221074&r1=1221073&r2=1221074&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Method.pm (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/Binding/Core/Method.pm Tue Dec 20 02:19:34 2011
@@ -18,74 +18,3 @@ use Clownfish;
1;
-__END__
-
-__POD__
-
-=head1 NAME
-
-Clownfish::Binding::Core::Method - Generate core C code for a method.
-
-=head1 DESCRIPTION
-
-Clownfish::Method is an abstract specification; this class generates C code
-which implements the specification.
-
-=head1 METHODS
-
-=head2 method_def
-
- my $c_code = Clownfish::Binding::Core::Method->method_def(
- method => $method,
- $class => $class,
- );
-
-Return C code for the static inline vtable method invocation function.
-
-=over
-
-=item * B<method> - A L<Clownfish::Method>.
-
-=item * B<class> - The L<Clownfish::Class> which will be invoking the method -
-LobsterClaw needs its own method invocation function even if the method was
-defined in Claw.
-
-=back
-
-=head2 typedef_dec
-
- my $c_code = Clownfish::Binding::Core::Method->typedef_dec($method);
-
-Return C code expressing a typedef declaration for the method.
-
-=head2 callback_dec
-
- my $c_code = Clownfish::Binding::Core::Method->callback_dec($method);
-
-Return C code declaring the Callback object for this method.
-
-=head2 callback_obj_def
-
- my $c_code
- = Clownfish::Binding::Core::Method->callback_obj_def($method);
-
-Return C code defining the Callback object for this method, which stores
-introspection data and a pointer to the callback function.
-
-=head2 callback_def
-
- my $c_code = Clownfish::Binding::Core::Method->callback_def($method);
-
-Return C code implementing a callback to the Host for this method. This code
-is used when a Host method has overridden a method in a Clownfish class.
-
-=head2 abstract_method_def
-
- my $c_code
- = Clownfish::Binding::Core::Method->abstract_method_def($method);
-
-Return C code implementing a version of the method which throws an "abstract
-method" error at runtime, for methods which are declared as "abstract" in a
-Clownfish header file.
-
-=cut
Modified: incubator/lucy/trunk/clownfish/src/CFCBindClass.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCBindClass.h?rev=1221074&r1=1221073&r2=1221074&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCBindClass.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCBindClass.h Tue Dec 20 02:19:34 2011
@@ -14,6 +14,12 @@
* limitations under the License.
*/
+/** Clownfish::Binding::Core::Class - Generate core C code for a class.
+ *
+ * Clownfish::Class is an abstract specification for a class. This module
+ * autogenerates the C code with implements that specification.
+ */
+
#ifndef H_CFCBINDCLASS
#define H_CFCBINDCLASS
@@ -25,6 +31,9 @@ typedef struct CFCBindClass CFCBindClass
struct CFCClass;
+/**
+ * @param client A Clownfish::Class.
+ */
struct CFCBindClass*
CFCBindClass_new(struct CFCClass *client);
@@ -34,9 +43,15 @@ CFCBindClass_init(struct CFCBindClass *s
void
CFCBindClass_destroy(CFCBindClass *self);
+/** Return the .h file which contains autogenerated C code defining the
+ * class's interface: all method invocation functions, etc...
+ */
char*
CFCBindClass_to_c_header(CFCBindClass *self);
+/** Return the .c file which contains autogenerated C code necessary for the
+ * class to function properly.
+ */
char*
CFCBindClass_to_c(CFCBindClass *self);
Modified: incubator/lucy/trunk/clownfish/src/CFCBindCore.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCBindCore.h?rev=1221074&r1=1221073&r2=1221074&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCBindCore.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCBindCore.h Tue Dec 20 02:19:34 2011
@@ -14,6 +14,13 @@
* limitations under the License.
*/
+/** Clownfish::Binding::Core - Generate core C code for a
+ * Clownfish::Hierarchy.
+ *
+ * A Clownfish::Hierarchy describes an abstract specifiction for a class
+ * hierarchy; Clownfish::Binding::Core is responsible for auto-generating C
+ * code which implements that specification.
+ */
#ifndef H_CFCBINDCORE
#define H_CFCBINDCORE
@@ -24,6 +31,15 @@ extern "C" {
typedef struct CFCBindCore CFCBindCore;
struct CFCHierarchy;
+
+/**
+ * @param hierarchy A L<Clownfish::Hierarchy>.
+ * @param dest The directory where C output files will be written.
+ * @param header Text which will be prepended to each generated C file --
+ * typically, an "autogenerated file" warning.
+ * @param footer Text to be appended to the end of each generated C file --
+ * typically copyright information.
+ */
CFCBindCore*
CFCBindCore_new(struct CFCHierarchy *hierarchy, const char *dest,
const char *header, const char *footer);
@@ -35,6 +51,10 @@ CFCBindCore_init(CFCBindCore *self, stru
void
CFCBindCore_destroy(CFCBindCore *self);
+/** Call <code>CFCHierarchy_propagate_modified</code>to establish which
+ * classes do not have up-to-date generated .c and .h files, then traverse the
+ * hierarchy writing all necessary files.
+ */
int
CFCBindCore_write_all_modified(CFCBindCore *self, int modified);
Modified: incubator/lucy/trunk/clownfish/src/CFCBindFile.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCBindFile.h?rev=1221074&r1=1221073&r2=1221074&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCBindFile.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCBindFile.h Tue Dec 20 02:19:34 2011
@@ -17,12 +17,34 @@
#ifndef H_CFCBINDFILE
#define H_CFCBINDFILE
+/** Clownfish::Binding::Core::File - Generate core C code for a Clownfish file.
+ *
+ * This module is the companion to Clownfish::File, generating the C code
+ * needed to implement the file's specification.
+ *
+ * There is a one-to-one mapping between Clownfish header files and
+ * autogenerated .h and .c files. If Foo.cfh includes both Foo and
+ * Foo::FooJr, then it is necessary to pound-include "Foo.h" in order to get
+ * FooJr's interface -- not "Foo/FooJr.h", which won't exist.
+ */
+
#ifdef __cplusplus
extern "C" {
#endif
struct CFCFile;
+/** Generate a C header file containing all class declarations and literal C
+ * blocks.
+ *
+ * @param file A Clownfish::File.
+ * @param dest The directory under which autogenerated files are being
+ * written.
+ * @param header Text which will be prepended to each generated C file --
+ * typically, an "autogenerated file" warning.
+ * @param footer Text to be appended to the end of each generated C file --
+ * typically copyright information.
+ */
void
CFCBindFile_write_h(struct CFCFile *file, const char *dest,
const char *header, const char *footer);
Modified: incubator/lucy/trunk/clownfish/src/CFCBindFunction.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCBindFunction.h?rev=1221074&r1=1221073&r2=1221074&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCBindFunction.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCBindFunction.h Tue Dec 20 02:19:34 2011
@@ -14,6 +14,9 @@
* limitations under the License.
*/
+/** Clownfish::Binding::Core::Function - Generate core C code for a function.
+ */
+
#ifndef H_CFCBINDFUNCTION
#define H_CFCBINDFUNCTION
@@ -23,6 +26,8 @@ extern "C" {
struct CFCFunction;
+/** Return C code declaring the function's C implementation.
+ */
char*
CFCBindFunc_func_declaration(struct CFCFunction *func);
Modified: incubator/lucy/trunk/clownfish/src/CFCBindMethod.h
URL: http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCBindMethod.h?rev=1221074&r1=1221073&r2=1221074&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCBindMethod.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCBindMethod.h Tue Dec 20 02:19:34 2011
@@ -14,6 +14,12 @@
* limitations under the License.
*/
+/** Clownfish::Binding::Core::Method - Generate core C code for a method.
+ *
+ * Clownfish::Method is an abstract specification; this class generates C code
+ * which implements the specification.
+ */
+
#ifndef H_CFCBINDMETHOD
#define H_CFCBINDMETHOD
@@ -24,21 +30,42 @@ extern "C" {
struct CFCMethod;
struct CFCClass;
+/** Return C code for the static inline vtable method invocation function.
+ * @param method A L<Clownfish::Method>.
+ * @param class The L<Clownfish::Class> which will be invoking the method.
+ * (LobsterClaw needs its own method invocation function even if the method
+ * was defined in Claw.)
+ */
char*
CFCBindMeth_method_def(struct CFCMethod *method, struct CFCClass *klass);
+/** Return C code expressing a typedef declaration for the method.
+ */
char*
CFCBindMeth_typdef_dec(struct CFCMethod *method);
+/** Return C code declaring the Callback object for this method.
+ */
char*
CFCBindMeth_callback_dec(struct CFCMethod *method);
+/** Return C code defining the Callback object for this method, which stores
+ * introspection data and a pointer to the callback function.
+ */
char*
CFCBindMeth_callback_obj_def(struct CFCMethod *method, const char* offset);
+/** Return C code implementing a version of the method which throws an
+ * "abstract method" error at runtime, for methods which are declared as
+ * "abstract" in a Clownfish header file.
+ */
char*
CFCBindMeth_abstract_method_def(struct CFCMethod *method);
+/** Return C code implementing a callback to the Host for this method. This
+ * code is used when a Host method has overridden a method in a Clownfish
+ * class.
+ */
char*
CFCBindMeth_callback_def(struct CFCMethod *method);