[lucy-dev] Clownfish front-page docs

[Marvin Humphrey <ma...@rectangular.com>]

On Sat, Jun 22, 2013 at 6:57 AM,  <nw...@apache.org> 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

Re: [lucy-dev] Clownfish front-page docs

[Nick Wellnhofer <we...@aevum.de>]

On Jun 25, 2013, at 06:50 , Marvin Humphrey <ma...@rectangular.com> wrote:

> On Sat, Jun 22, 2013 at 6:57 AM,  <nw...@apache.org> wrote:
>> +=head1 NAME
>> +
>> +Clownfish - Short description.
>> +
> 
> I suggest...
> 
>    Clownfish - Symbiotic object system.

+1

>> +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".

Yes, I really wanted to say "A class's methods, functions…"

> 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.

+1

>> +=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.

Actually, I didn't finish the ABI stability changes for methods yet. But the infrastructure is all there. All that's missing is initializing the methods offsets during VTable bootstrap.

>> +=head1 USING CLOWNFISH CLASSES
>> +
>> +TODO: Simple introduction
> 
> This is using them from Perl?

No, I want to put an intro there on how to use Clownfish from C. It's the thing that I had planned for users of the C library. Since we don't have a language-independent documentation format yet, I would simply put it in the POD and refer C users there.

>> +=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 didn't check if that matches current CFC behaviour. That's one of the places where I documented what I think CFC should do without looking at the source.

> 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.

Now that I had a look at the code, I realize that CFC simply ignores the abstract modifier on classes. That makes sense and we should remove that section. But CFC should throw an error when it encounters an invalid modifier. Currently, those are silently ignored in many cases. For example, we also allow "final inert", "abstract inert", and "inline" non-inert functions which should all be errors.

I'm trying to make the documentation as strict as possible. Then we can make sure that CFC really checks all those "musts" and "must-nots". Unfortunately, we still can't test CFC exceptions from C, only from Perl.

>> +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.

Yes, it's probably better to document exactly what is generated.

> 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.

+1

Nick