[lucy-user] Re: Documentation missing file

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

On Sun, Sep 11, 2011 at 12:17:58PM +0200, goran kent wrote:
> Just a quick note:  the documentation is missing file:
> http://incubator.apache.org/lucy/docs/perl/Lucy/Plan/TextType.html
> linked from http://incubator.apache.org/lucy/docs/perl/Lucy/Plan/FullTextType.html

Thanks for the heads up.  Moving this thread to lucy-dev...

This is actually a code generation bug in
trunk/clownfish/lib/Clownfish/Binding/Perl/Class.pm rather than just a typo in
static POD.

Lucy::Plan::FullTextType and Lucy::Plan::StringType both inherit from
Lucy::Plan::TextType, an abstract class, which is not exposed via the Perl
documentation.  We've discussed consolidating FullTextType and StringType into
TextType, which would make this specific instance of the problem go away, but
wouldn't solve the general issue.

The POD for FullTextType is generated using the clownfish header file
trunk/core/Lucy/Plan/FullTextType.cfh as raw material.  An auxiliary
"INHERITANCE" section is assembled by walking the class's ancestors and
creating a link for each one, ultimately producing POD such as this:

    =head1 INHERITANCE

    Lucy::Plan::FullTextType isa L<Lucy::Plan::TextType> isa L<Lucy::Plan::FieldType> isa L<Lucy::Object::Obj>.

To address the problem, first we need to detect whether each of the ancestor
classes is exposed via the Perl bindings before generating that link.  Then
there are two possible approaches:

  1) Generate the text but don't link.
  2) Throw an error.  This will have the effect of forcing us to expose all
     ancestors for every class we expose via the Perl bindings.

I lean towards the more permissive option (#1, don't link).  I think that it
ought to be the main Clownfish compiler enforcing inheritance, by imposing the
constraint that all ancestors of a public class must also be public.  The
binding tools ought to be flexible so that the interface for a given host
language can be A) rolled out piecemeal and B) customized so that it is as
idiomatic as possible.

Marvin Humphrey

Re: [lucy-user] Re: Documentation missing file

[Peter Karman <pe...@peknet.com>]

Marvin Humphrey wrote on 09/11/2011 02:46 PM:

> To address the problem, first we need to detect whether each of the ancestor
> classes is exposed via the Perl bindings before generating that link.  Then
> there are two possible approaches:
> 
>   1) Generate the text but don't link.
>   2) Throw an error.  This will have the effect of forcing us to expose all
>      ancestors for every class we expose via the Perl bindings.
> 
> I lean towards the more permissive option (#1, don't link).  I think that it
> ought to be the main Clownfish compiler enforcing inheritance, by imposing the
> constraint that all ancestors of a public class must also be public.  The
> binding tools ought to be flexible so that the interface for a given host
> language can be A) rolled out piecemeal and B) customized so that it is as
> idiomatic as possible.
> 

+1

-- 
Peter Karman  .  http://peknet.com/  .  peter@peknet.com