Change default function for ctor POD By default, the POD for Perl constructors is taken from the "alias" instead of "init".
Project: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/repo Commit: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/commit/db2ea9ad Tree: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/tree/db2ea9ad Diff: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/diff/db2ea9ad Branch: refs/heads/master Commit: db2ea9ad0fc304a9b1bcfe28954194b267847f4b Parents: 65cca17 Author: Nick Wellnhofer <[email protected]> Authored: Tue Feb 9 14:29:50 2016 +0100 Committer: Nick Wellnhofer <[email protected]> Committed: Tue Feb 9 14:44:49 2016 +0100 ---------------------------------------------------------------------- compiler/perl/lib/Clownfish/CFC.pm | 10 ++-- compiler/perl/lib/Clownfish/CFC.xs | 8 ++-- compiler/src/CFCPerlPod.c | 16 +++---- compiler/src/CFCPerlPod.h | 8 ++-- .../perl/buildlib/Clownfish/Build/Binding.pm | 48 +++++++------------- 5 files changed, 36 insertions(+), 54 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/db2ea9ad/compiler/perl/lib/Clownfish/CFC.pm ---------------------------------------------------------------------- diff --git a/compiler/perl/lib/Clownfish/CFC.pm b/compiler/perl/lib/Clownfish/CFC.pm index 6f03364..0344bcb 100644 --- a/compiler/perl/lib/Clownfish/CFC.pm +++ b/compiler/perl/lib/Clownfish/CFC.pm @@ -846,16 +846,16 @@ BEGIN { XSLoader::load( 'Clownfish::CFC', '0.4.0' ) } } my %add_constructor_PARAMS = ( - alias => undef, - initializer => undef, - sample => undef, - pod => undef, + alias => undef, + pod_func => undef, + sample => undef, + pod => undef, ); sub add_constructor { my ( $self, %args ) = @_; verify_args( \%add_constructor_PARAMS, %args ) or confess $@; - _add_constructor( $self, @args{qw( alias initializer sample pod )} ); + _add_constructor( $self, @args{qw( alias pod_func sample pod )} ); } } http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/db2ea9ad/compiler/perl/lib/Clownfish/CFC.xs ---------------------------------------------------------------------- diff --git a/compiler/perl/lib/Clownfish/CFC.xs b/compiler/perl/lib/Clownfish/CFC.xs index c942338..efb68a2 100644 --- a/compiler/perl/lib/Clownfish/CFC.xs +++ b/compiler/perl/lib/Clownfish/CFC.xs @@ -2316,18 +2316,18 @@ PPCODE: CFCPerlPod_add_method(self, alias, method, sample, pod); void -_add_constructor(self, alias_sv, init_sv, sample_sv, pod_sv) +_add_constructor(self, alias_sv, func_sv, sample_sv, pod_sv) CFCPerlPod *self; SV *alias_sv; - SV *init_sv; + SV *func_sv; SV *sample_sv; SV *pod_sv; PPCODE: const char *alias = SvPOK(alias_sv) ? SvPVutf8_nolen(alias_sv) : NULL; - const char *init = SvPOK(init_sv) ? SvPVutf8_nolen(init_sv) : NULL; + const char *func = SvPOK(func_sv) ? SvPVutf8_nolen(func_sv) : NULL; const char *sample = SvPOK(sample_sv) ? SvPVutf8_nolen(sample_sv) : NULL; const char *pod = SvPOK(pod_sv) ? SvPVutf8_nolen(pod_sv) : NULL; - CFCPerlPod_add_constructor(self, alias, init, sample, pod); + CFCPerlPod_add_constructor(self, alias, func, sample, pod); SV* methods_pod(self, klass) http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/db2ea9ad/compiler/src/CFCPerlPod.c ---------------------------------------------------------------------- diff --git a/compiler/src/CFCPerlPod.c b/compiler/src/CFCPerlPod.c index 97f93c8..5cbd312 100644 --- a/compiler/src/CFCPerlPod.c +++ b/compiler/src/CFCPerlPod.c @@ -150,14 +150,14 @@ CFCPerlPod_add_method(CFCPerlPod *self, const char *alias, const char *method, void CFCPerlPod_add_constructor(CFCPerlPod *self, const char *alias, - const char *initializer, const char *sample, + const char *pod_func, const char *sample, const char *pod) { self->num_constructors++; size_t size = self->num_constructors * sizeof(NamePod); self->constructors = (NamePod*)REALLOCATE(self->constructors, size); NamePod *slot = &self->constructors[self->num_constructors - 1]; slot->alias = CFCUtil_strdup(alias ? alias : "new"); - slot->func = CFCUtil_strdup(initializer ? initializer : "init"); + slot->func = pod_func ? CFCUtil_strdup(pod_func) : NULL; slot->sample = sample ? CFCUtil_strdup(sample) : NULL; slot->pod = pod ? CFCUtil_strdup(pod) : NULL; } @@ -294,16 +294,14 @@ CFCPerlPod_constructors_pod(CFCPerlPod *self, CFCClass *klass) { pod = CFCUtil_cat(pod, slot.pod, "\n", NULL); } else { - CFCFunction *init_func = CFCClass_function(klass, slot.func); - if (!init_func) { - init_func = CFCClass_function(klass, slot.alias); - } - if (!init_func) { + const char *func_name = slot.func ? slot.func : slot.alias; + CFCFunction *pod_func = CFCClass_function(klass, func_name); + if (!pod_func) { CFCUtil_die("Can't find constructor '%s' in class '%s'", - slot.alias, CFCClass_get_name(klass)); + func_name, CFCClass_get_name(klass)); } char *sub_pod - = CFCPerlPod_gen_subroutine_pod(init_func, slot.alias, klass, + = CFCPerlPod_gen_subroutine_pod(pod_func, slot.alias, klass, slot.sample, class_name, true); pod = CFCUtil_cat(pod, sub_pod, NULL); FREEMEM(sub_pod); http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/db2ea9ad/compiler/src/CFCPerlPod.h ---------------------------------------------------------------------- diff --git a/compiler/src/CFCPerlPod.h b/compiler/src/CFCPerlPod.h index 1d63a4a..8ab88c2 100644 --- a/compiler/src/CFCPerlPod.h +++ b/compiler/src/CFCPerlPod.h @@ -55,16 +55,16 @@ CFCPerlPod_add_method(CFCPerlPod *self, const char *alias, const char *method, /** Add pod for a constructor. * * @param alias The name of the constructor, spelled as it will be used from - * Perl-space. - * @param initializer The name of the initialization routine from the - * Clownfish class. Defaults to "init". + * Perl-space. Defaults to "new". + * @param pod_func The name of the function from which the constructor's + * documentation should be taken. Defaults to the alias. * @param sample An optional Perl usage sample. * @param pod Optional verbatim POD, which will override all POD which would * otherwise have been generated. */ void CFCPerlPod_add_constructor(CFCPerlPod *self, const char *alias, - const char *initializer, const char *sample, + const char *pod_func, const char *sample, const char *pod); /** Generate POD for a METHODS section and possibly an ABSTRACT METHODS http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/db2ea9ad/runtime/perl/buildlib/Clownfish/Build/Binding.pm ---------------------------------------------------------------------- diff --git a/runtime/perl/buildlib/Clownfish/Build/Binding.pm b/runtime/perl/buildlib/Clownfish/Build/Binding.pm index bf73807..2ee3da0 100644 --- a/runtime/perl/buildlib/Clownfish/Build/Binding.pm +++ b/runtime/perl/buildlib/Clownfish/Build/Binding.pm @@ -131,7 +131,7 @@ END_SYNOPSIS Create a Blob containing the passed-in bytes. END_CONSTRUCTOR $pod_spec->set_synopsis($synopsis); - $pod_spec->add_constructor( alias => 'new', pod => $constructor ); + $pod_spec->add_constructor( pod => $constructor ); my $xs_code = <<'END_XS_CODE'; MODULE = Clownfish PACKAGE = Clownfish::Blob @@ -184,12 +184,12 @@ END_DESCRIPTION my $bool = Clownfish::Boolean->singleton($truth_value); -Return a Boolean singleton representing either true or false depending -on the supplied truth value. +Return either C<$true_singleton> or C<$false_singleton> depending on the +supplied value. END_CONSTRUCTOR $pod_spec->set_synopsis($synopsis); $pod_spec->set_description($description); - $pod_spec->add_constructor( alias => 'new', pod => $constructor ); + $pod_spec->add_constructor( pod => $constructor ); my $xs_code = <<'END_XS_CODE'; MODULE = Clownfish PACKAGE = Clownfish::Boolean @@ -229,7 +229,7 @@ END_SYNOPSIS Create a ByteBuf containing the passed-in bytes. END_CONSTRUCTOR $pod_spec->set_synopsis($synopsis); - $pod_spec->add_constructor( alias => 'new', pod => $constructor ); + $pod_spec->add_constructor( pod => $constructor ); my $xs_code = <<'END_XS_CODE'; MODULE = Clownfish PACKAGE = Clownfish::ByteBuf @@ -270,10 +270,10 @@ sub bind_charbuf { print $buf->to_string; END_SYNOPSIS my $constructor = <<'END_CONSTRUCTOR'; - my $buf = Clownfish::CharBuf->new( size => 256 ); + my $buf = Clownfish::CharBuf->new( capacity => 256 ); END_CONSTRUCTOR $pod_spec->set_synopsis($synopsis); - $pod_spec->add_constructor( alias => 'new', sample => $constructor ); + $pod_spec->add_constructor( sample => $constructor ); my $binding = Clownfish::CFC::Binding::Perl::Class->new( parcel => "Clownfish", @@ -298,7 +298,7 @@ END_SYNOPSIS Return a String containing the passed-in Perl string. END_CONSTRUCTOR $pod_spec->set_synopsis($synopsis); - $pod_spec->add_constructor( alias => 'new', pod => $constructor ); + $pod_spec->add_constructor( pod => $constructor ); my $xs_code = <<'END_XS_CODE'; MODULE = Clownfish PACKAGE = Clownfish::String @@ -498,7 +498,7 @@ END_CONSTRUCTOR Store a key-value pair. END_POD $pod_spec->set_synopsis($synopsis); - $pod_spec->add_constructor( alias => 'new', sample => $constructor ); + $pod_spec->add_constructor( sample => $constructor ); $pod_spec->add_method( method => 'Store', alias => 'store', @@ -549,14 +549,10 @@ sub bind_hashiterator { } END_SYNOPSIS my $constructor = <<'END_CONSTRUCTOR'; -=head2 new - my $iter = Clownfish::HashIterator->new($hash); - -Return a HashIterator for the passed-in Hash. END_CONSTRUCTOR $pod_spec->set_synopsis($synopsis); - $pod_spec->add_constructor( alias => 'new', pod => $constructor ); + $pod_spec->add_constructor( sample => $constructor ); my $xs_code = <<'END_XS_CODE'; MODULE = Clownfish PACKAGE = Clownfish::HashIterator @@ -593,14 +589,10 @@ sub bind_float { my $value = $float->get_value; END_SYNOPSIS my $constructor = <<'END_CONSTRUCTOR'; -=head2 new - my $float = Clownfish::Float->new($value); - -Create a Float containing the passed-in value. END_CONSTRUCTOR $pod_spec->set_synopsis($synopsis); - $pod_spec->add_constructor( alias => 'new', pod => $constructor ); + $pod_spec->add_constructor( sample => $constructor ); my $xs_code = <<'END_XS_CODE'; MODULE = Clownfish PACKAGE = Clownfish::Float @@ -637,14 +629,10 @@ sub bind_integer { my $value = $integer->get_value; END_SYNOPSIS my $constructor = <<'END_CONSTRUCTOR'; -=head2 new - my $integer = Clownfish::Integer->new($value); - -Create an Integer containing the passed-in value. END_CONSTRUCTOR $pod_spec->set_synopsis($synopsis); - $pod_spec->add_constructor( alias => 'new', pod => $constructor ); + $pod_spec->add_constructor( sample => $constructor ); my $xs_code = <<'END_XS_CODE'; MODULE = Clownfish PACKAGE = Clownfish::Integer @@ -860,7 +848,7 @@ END_CONSTRUCTOR Store an element at index C<tick>, possibly displacing an existing element. END_POD $pod_spec->set_synopsis($synopsis); - $pod_spec->add_constructor( alias => 'new', sample => $constructor ); + $pod_spec->add_constructor( sample => $constructor ); $pod_spec->add_method( method => 'Store', alias => 'store', @@ -922,12 +910,8 @@ sub bind_class { my $class = Clownfish::Class->fetch_class('Foo::Bar'); my $subclass = Clownfish::Class->singleton('Foo::Bar::Jr', $class); END_SYNOPSIS - my $fetch_class_pod = <<'END_CONSTRUCTOR'; -=head2 fetch_class - + my $fetch_class_sample = <<'END_CONSTRUCTOR'; my $class = Clownfish::Class->fetch_class($class_name); - -Find a registered class. May return undef if the class is not registered. END_CONSTRUCTOR my $singleton_sample = <<'END_CONSTRUCTOR'; my $class = Clownfish::Class->singleton( @@ -937,8 +921,8 @@ END_CONSTRUCTOR END_CONSTRUCTOR $pod_spec->set_synopsis($synopsis); $pod_spec->add_constructor( - alias => 'fetch_class', - pod => $fetch_class_pod, + alias => 'fetch_class', + sample => $fetch_class_sample, ); $pod_spec->add_constructor( alias => 'singleton',
