Add POD for public novel methods by default
Project: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/repo Commit: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/commit/f71e072a Tree: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/tree/f71e072a Diff: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/diff/f71e072a Branch: refs/heads/master Commit: f71e072acca38540c5ee8a448ece5b8d10c31f04 Parents: 0bd951a Author: Nick Wellnhofer <[email protected]> Authored: Thu Aug 20 16:03:37 2015 +0200 Committer: Nick Wellnhofer <[email protected]> Committed: Sun Aug 30 19:16:42 2015 +0200 ---------------------------------------------------------------------- compiler/src/CFCPerlPod.c | 77 +++++++++++++++----- .../perl/buildlib/Clownfish/Build/Binding.pm | 20 +++-- 2 files changed, 69 insertions(+), 28 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/f71e072a/compiler/src/CFCPerlPod.c ---------------------------------------------------------------------- diff --git a/compiler/src/CFCPerlPod.c b/compiler/src/CFCPerlPod.c index 8b728e0..3699acd 100644 --- a/compiler/src/CFCPerlPod.c +++ b/compiler/src/CFCPerlPod.c @@ -29,6 +29,7 @@ #include "CFCMethod.h" #include "CFCParcel.h" #include "CFCParamList.h" +#include "CFCPerlMethod.h" #include "CFCFunction.h" #include "CFCDocuComment.h" #include "CFCUri.h" @@ -168,6 +169,7 @@ CFCPerlPod_methods_pod(CFCPerlPod *self, CFCClass *klass) { const char *class_name = CFCClass_get_name(klass); char *abstract_pod = CFCUtil_strdup(""); char *methods_pod = CFCUtil_strdup(""); + for (size_t i = 0; i < self->num_methods; i++) { NamePod meth_spec = self->methods[i]; CFCMethod *method = CFCClass_method(klass, meth_spec.func); @@ -198,6 +200,47 @@ CFCPerlPod_methods_pod(CFCPerlPod *self, CFCClass *klass) { FREEMEM(meth_pod); } + // Add POD for public novel methods by default. + CFCMethod **fresh_methods = CFCClass_fresh_methods(klass); + for (int meth_num = 0; fresh_methods[meth_num] != NULL; meth_num++) { + CFCMethod *method = fresh_methods[meth_num]; + if (!CFCMethod_public(method) || !CFCMethod_novel(method)) { + continue; + } + if (CFCMethod_excluded_from_host(method)) { + continue; + } + if (!CFCMethod_can_be_bound(method)) { + continue; + } + + const char *name = CFCMethod_get_name(method); + + // Skip methods that were added manually. + int found = false; + for (size_t j = 0; j < self->num_methods; j++) { + const char *other_name = self->methods[j].func; + if (other_name && strcmp(other_name, name) == 0) { + found = true; + break; + } + } + if (found) { continue; } + + char *perl_name = CFCPerlMethod_perl_name(method); + char *meth_pod + = CFCPerlPod_gen_subroutine_pod((CFCFunction*)method, perl_name, + klass, NULL, class_name, false); + if (CFCMethod_abstract(method)) { + abstract_pod = CFCUtil_cat(abstract_pod, meth_pod, NULL); + } + else { + methods_pod = CFCUtil_cat(methods_pod, meth_pod, NULL); + } + FREEMEM(meth_pod); + FREEMEM(perl_name); + } + char *pod = CFCUtil_strdup(""); if (strlen(abstract_pod)) { pod = CFCUtil_cat(pod, "=head1 ABSTRACT METHODS\n\n", abstract_pod, NULL); @@ -249,23 +292,6 @@ CFCPerlPod_gen_subroutine_pod(CFCFunction *func, int num_vars = (int)CFCParamList_num_vars(param_list); char *pod = CFCUtil_sprintf("=head2 %s", alias); - // Get documentation, which may be inherited. - CFCDocuComment *docucomment = CFCFunction_get_docucomment(func); - if (!docucomment) { - const char *func_name = CFCFunction_get_name(func); - CFCClass *parent = klass; - while (NULL != (parent = CFCClass_get_parent(parent))) { - CFCFunction *parent_func - = (CFCFunction*)CFCClass_method(parent, func_name); - if (!parent_func) { break; } - docucomment = CFCFunction_get_docucomment(parent_func); - if (docucomment) { break; } - } - } - if (!docucomment) { - CFCUtil_die("No DocuComment for '%s' in '%s'", alias, class_name); - } - // Build string summarizing arguments to use in header. if (num_vars > 2 || (is_constructor && num_vars > 1)) { pod = CFCUtil_cat(pod, "( I<[labeled params]> )\n\n", NULL); @@ -287,6 +313,23 @@ CFCPerlPod_gen_subroutine_pod(CFCFunction *func, pod = CFCUtil_cat(pod, code_sample, "\n", NULL); } + // Get documentation, which may be inherited. + CFCDocuComment *docucomment = CFCFunction_get_docucomment(func); + if (!docucomment) { + const char *func_name = CFCFunction_get_name(func); + CFCClass *parent = klass; + while (NULL != (parent = CFCClass_get_parent(parent))) { + CFCFunction *parent_func + = (CFCFunction*)CFCClass_method(parent, func_name); + if (!parent_func) { break; } + docucomment = CFCFunction_get_docucomment(parent_func); + if (docucomment) { break; } + } + } + if (!docucomment) { + return pod; + } + // Incorporate "description" text from DocuComment. const char *long_doc = CFCDocuComment_get_description(docucomment); if (long_doc && strlen(long_doc)) { http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/f71e072a/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 2b07aee..417e966 100644 --- a/runtime/perl/buildlib/Clownfish/Build/Binding.pm +++ b/runtime/perl/buildlib/Clownfish/Build/Binding.pm @@ -354,11 +354,6 @@ END_XS_CODE } sub bind_obj { - my @exposed = qw( - To_String - Equals - ); - my $pod_spec = Clownfish::CFC::Binding::Perl::Pod->new; my $synopsis = <<'END_SYNOPSIS'; package MyObj; @@ -434,17 +429,20 @@ instantiate objects of class "Clownfish::Obj" directly causes an error. Takes no arguments; if any are supplied, an error will be reported. - -=head1 DESTRUCTOR - -=head2 DESTROY +END_DESCRIPTION + my $destroy_pod = <<'END_POD'; +=head2 DESTROY() All Clownfish classes implement a DESTROY method; if you override it in a subclass, you must call C<< $self->SUPER::DESTROY >> to avoid leaking memory. -END_DESCRIPTION +END_POD $pod_spec->set_synopsis($synopsis); $pod_spec->set_description($description); - $pod_spec->add_method( method => $_, alias => lc($_) ) for @exposed; + $pod_spec->add_method( + method => 'Destroy', + alias => 'DESTROY', + pod => $destroy_pod, + ); my $xs_code = <<'END_XS_CODE'; MODULE = Clownfish PACKAGE = Clownfish::Obj
