On Sat, Jun 22, 2013 at 6:57 AM, <[email protected]> wrote: > Updated Branches: > refs/heads/separate-clownfish-wip5 9e0f1cc89 -> 8db0310d2 > > Start with Clownfish documentation
All right! It's ON. The bulk of this large patch looks great, Nick -- and I'm so glad that you wrote it, because I would have agonized over it! Please assume that if I have not commented on some section, lazy consensus applies. > Project: http://git-wip-us.apache.org/repos/asf/lucy/repo > Commit: http://git-wip-us.apache.org/repos/asf/lucy/commit/8db0310d > Tree: http://git-wip-us.apache.org/repos/asf/lucy/tree/8db0310d > Diff: http://git-wip-us.apache.org/repos/asf/lucy/diff/8db0310d > +=head1 NAME > + > +Clownfish - Short description. > + I suggest... Clownfish - Symbiotic object system. The rationale for emphasizing the word "symbiotic" is that it articulates a vision for this product which differentiates it from other object systems. We want to do something different from C++, GObject, Parrot, Mono, GNUstep, and others which have gone before. > +Clownfish is an object system for C designed to easily create bindings for > +dynamic languages, so-called host languages. Classes are declared in > Clownfish > +header files with a C<.cfh> extension. The Clownfish headers are used by the > +Clownfish compiler to generate C header files and host language bindings. > +Class methods, functions and variables are defined in normal C source files. Nit: "Class methods" should probably be either "Instance methods", "Object methods" or "Dynamic methods". I suggest a change in the first sentence, as well: Clownfish is a "symbiotic" object system for C which is designed to pair with a "host" dynamic language environment, facilitating the development of high performance host language extensions. Clownfish classes are declared in header files with a C<.cfh> extension. The Clownfish headers are used by the Clownfish compiler to generate C header files and host language bindings. Instance methods, functions and variables are defined in normal C source files. > +=item * > + > +Guaranteed ABI stability when adding or reordering methods or instance > +variables. Interesting wording. I agree that it probably isn't worthwhile to distinguish between methods and instance variables, even though we only continue to have fragile ABI problems with instance variables. But hopefully this will change soon anyway. > +=head1 USING CLOWNFISH CLASSES > + > +TODO: Simple introduction This is using them from Perl? > +=head3 Abstract classes > + > +Only abstract classes may contain abstract methods. They must not be > +instantiated directly. Haha, is that true? That limitation never occurred to me before, so if I programmed it into CFC, it was by accident. I suppose that such a restriction allows us to error out at compile-time rather than runtime when some method is not implemented in a compiled extension. Fine, that works. Better to be more strict now because we'll have the option of relaxing the rule later. > +This will generate: > + > + /* Wrapper for dynamic dispatch */ > + void > + Pfind_VisGraph_Add_Node(pfind_VisibilityGraph *self, pfind_Node *node); Technically this will be a static inline function. Eventually somebody might get confused by this when they can't find the symbol. > +=head1 COPYRIGHT > + > +Apache Clownfish is distributed under the Apache License, Version 2.0, as > +described in the file C<LICENSE> included with the distribution. Before we refer to this product with the "Apache" prefix, i.e. as "Apache Clownfish", I think we should check in with VP Brand Management. There are two possible tracks for Clownfish. If people end up using it to build non-Lucy-related products, it will almost certainly split off from Lucy and enter the Incubator on a path to becoming an independent top-level Apache project. The other possibility is that Clownfish will remain a utility for creating compiled Lucy extensions for the indefinite future. We are completely justified releasing Clownfish as a public API based on what it offers to Lucy users -- and because of that, we don't have to go through the Incubator yet. I'm just not clear on what the deal is with regards to a TLP launching a secondary product. I can see arguments for "Apache Clownfish", "Apache Lucy Clownfish" (blech), and just "Clownfish". Let's ask. Marvin Humphrey
