Author: marvin
Date: Tue Mar 13 22:44:28 2012
New Revision: 1300388
URL: http://svn.apache.org/viewvc?rev=1300388&view=rev
Log:
Flesh out CFCPerl docs.
Add docs for routines which had been missing them previously. Make a few
corrections and make some superficial name changes for clarity's sake.
Modified:
incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC.xs
incubator/lucy/trunk/clownfish/src/CFCPerl.h
incubator/lucy/trunk/clownfish/src/CFCPerlClass.h
incubator/lucy/trunk/clownfish/src/CFCPerlConstructor.h
incubator/lucy/trunk/clownfish/src/CFCPerlPod.c
incubator/lucy/trunk/clownfish/src/CFCPerlPod.h
incubator/lucy/trunk/clownfish/src/CFCPerlSub.h
Modified: incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC.xs
URL:
http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC.xs?rev=1300388&r1=1300387&r2=1300388&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC.xs (original)
+++ incubator/lucy/trunk/clownfish/perl/lib/Clownfish/CFC.xs Tue Mar 13
22:44:28 2012
@@ -2180,16 +2180,16 @@ CODE:
OUTPUT: RETVAL
SV*
-_gen_subroutine_pod(self, func, sub_name, klass, code_sample, class_name,
is_constructor)
+_gen_subroutine_pod(self, func, alias, klass, code_sample, class_name,
is_constructor)
CFCPerlPod *self;
CFCFunction *func;
- const char *sub_name;
+ const char *alias;
CFCClass *klass;
const char *code_sample;
const char *class_name;
int is_constructor;
CODE:
- char *value = CFCPerlPod_gen_subroutine_pod(self, func, sub_name, klass,
+ char *value = CFCPerlPod_gen_subroutine_pod(self, func, alias, klass,
code_sample, class_name,
is_constructor);
RETVAL = S_sv_eat_c_string(value);
Modified: incubator/lucy/trunk/clownfish/src/CFCPerl.h
URL:
http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerl.h?rev=1300388&r1=1300387&r2=1300388&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerl.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerl.h Tue Mar 13 22:44:28 2012
@@ -99,6 +99,8 @@ CFCPerl_write_boot(CFCPerl *self);
void
CFCPerl_write_bindings(CFCPerl *self);
+/** Generate the "typemap" file needed by the XS compiler.
+ */
void
CFCPerl_write_xs_typemap(CFCPerl *self);
Modified: incubator/lucy/trunk/clownfish/src/CFCPerlClass.h
URL:
http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerlClass.h?rev=1300388&r1=1300387&r2=1300388&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerlClass.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerlClass.h Tue Mar 13 22:44:28 2012
@@ -58,44 +58,61 @@ CFCPerlClass_add_to_registry(CFCPerlClas
CFCPerlClass*
CFCPerlClass_singleton(const char *class_name);
-/** All registered bindings.
+/** All registered class bindings.
*/
CFCPerlClass**
CFCPerlClass_registry();
+/** Release all memory and references held by the registry.
+ */
void
CFCPerlClass_clear_registry(void);
+/** Override the specification for a method being made available from Perl.
+ * The default spec is to make the method available under a lower-cased alias
+ * of the Clownfish method name.
+ *
+ * @param alias The Perl name for the method.
+ * @param method The Clownfish name for the method.
+ */
void
CFCPerlClass_bind_method(CFCPerlClass *self, const char *alias,
const char *method);
+/** Specify that a constructor should be made available from Perl-space.
+ *
+ * @param alias The Perl name for the constructor (default "new").
+ * @param initializer The Clownfish name for the initialization function which
+ * will be invoked (default "init").
+ */
void
CFCPerlClass_bind_constructor(CFCPerlClass *self, const char *alias,
const char *initializer);
-/** Don't generate a binding for the specified method automatically.
+/** Block the automatic generation of a method binding.
*/
void
CFCPerlClass_exclude_method(CFCPerlClass *self, const char *method);
-/** Don't generate a constructor named "new" from "init" automatically.
+/** Block the automatic generation of a constructor binding.
*/
void
CFCPerlClass_exclude_constructor(CFCPerlClass *self);
-/** Return an array of Clownfish::CFC::Binding::Perl::Method objects.
+/** Return an array of Clownfish::CFC::Binding::Perl::Method objects
+ * representing all bound methods.
*/
struct CFCPerlMethod**
CFCPerlClass_method_bindings(CFCPerlClass *self);
-/** Return an array of Clownfish::CFC::Binding::Perl::Constructor objects.
+/** Return an array of Clownfish::CFC::Binding::Perl::Constructor objects
+ * representing all bound constructors.
*/
struct CFCPerlConstructor**
CFCPerlClass_constructor_bindings(CFCPerlClass *self);
-/** Auto-generate POD according to the make_pod spec, if such a spec was
- * supplied.
+/** Auto-generate POD according to the spec supplied via set_pod_spec(). If
+ * no spec was supplied, return NULL.
*/
char*
CFCPerlClass_create_pod(CFCPerlClass *self);
@@ -105,7 +122,7 @@ CFCPerlClass_create_pod(CFCPerlClass *se
struct CFCClass*
CFCPerlClass_get_client(CFCPerlClass *self);
-/** Accessor.
+/** Accessor for class name.
*/
const char*
CFCPerlClass_get_class_name(CFCPerlClass *self);
@@ -120,9 +137,14 @@ CFCPerlClass_append_xs(CFCPerlClass *sel
const char*
CFCPerlClass_get_xs_code(CFCPerlClass *self);
+/** Supply a specification which will cause POD to be generated for this class
+ * binding.
+ */
void
CFCPerlClass_set_pod_spec(CFCPerlClass *self, struct CFCPerlPod *pod_spec);
+/** Accessor for pod spec.
+ */
struct CFCPerlPod*
CFCPerlClass_get_pod_spec(CFCPerlClass *self);
Modified: incubator/lucy/trunk/clownfish/src/CFCPerlConstructor.h
URL:
http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerlConstructor.h?rev=1300388&r1=1300387&r2=1300388&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerlConstructor.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerlConstructor.h Tue Mar 13 22:44:28
2012
@@ -34,12 +34,10 @@ struct CFCClass;
*/
/**
- * @param class A L<Clownfish::CFC::Class>.
- * @param alias A specifier for the name of the constructor, and
- * optionally, a specifier for the implementing function. If C<alias> has a
pipe
- * character in it, the text to the left of the pipe will be used as the Perl
- * alias, and the text to the right will be used to determine which C function
- * should be bound. The default function is "init".
+ * @param klass A L<Clownfish::CFC::Class>.
+ * @param alias The Perl name for the constructor.
+ * @param initializer The name of the function which should be bound (default
+ * "init").
*/
CFCPerlConstructor*
CFCPerlConstructor_new(struct CFCClass *klass, const char *alias,
Modified: incubator/lucy/trunk/clownfish/src/CFCPerlPod.c
URL:
http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerlPod.c?rev=1300388&r1=1300387&r2=1300388&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerlPod.c (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerlPod.c Tue Mar 13 22:44:28 2012
@@ -145,7 +145,6 @@ CFCPerlPod_get_description(CFCPerlPod *s
return self->description;
}
-// Create METHODS, possibly including an ABSTRACT METHODS section.
char*
CFCPerlPod_methods_pod(CFCPerlPod *self, CFCClass *klass) {
const char *class_name = CFCClass_get_class_name(klass);
@@ -196,7 +195,6 @@ CFCPerlPod_methods_pod(CFCPerlPod *self,
return pod;
}
-// Create CONSTRUCTORS.
char*
CFCPerlPod_constructors_pod(CFCPerlPod *self, CFCClass *klass) {
if (!self->num_constructors) {
@@ -268,17 +266,17 @@ S_global_replace(const char *string, con
char*
CFCPerlPod_gen_subroutine_pod(CFCPerlPod *self, CFCFunction *func,
- const char *sub_name, CFCClass *klass,
+ const char *alias, CFCClass *klass,
const char *code_sample,
const char *class_name, int is_constructor) {
// Only allow "public" subs to be exposed as part of the public API.
if (!CFCSymbol_public((CFCSymbol*)func)) {
- CFCUtil_die("%s#%s is not public", class_name, sub_name);
+ CFCUtil_die("%s#%s is not public", class_name, alias);
}
CFCParamList *param_list = CFCFunction_get_param_list(func);
int num_vars = CFCParamList_num_vars(param_list);
- char *pod = CFCUtil_cat(CFCUtil_strdup(""), "=head2 ", sub_name, NULL);
+ char *pod = CFCUtil_cat(CFCUtil_strdup(""), "=head2 ", alias, NULL);
// Get documentation, which may be inherited.
CFCDocuComment *docucomment = CFCFunction_get_docucomment(func);
@@ -294,7 +292,7 @@ CFCPerlPod_gen_subroutine_pod(CFCPerlPod
}
}
if (!docucomment) {
- CFCUtil_die("No DocuComment for '%s' in '%s'", sub_name, class_name);
+ CFCUtil_die("No DocuComment for '%s' in '%s'", alias, class_name);
}
// Build string summarizing arguments to use in header.
Modified: incubator/lucy/trunk/clownfish/src/CFCPerlPod.h
URL:
http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerlPod.h?rev=1300388&r1=1300387&r2=1300388&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerlPod.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerlPod.h Tue Mar 13 22:44:28 2012
@@ -67,30 +67,53 @@ CFCPerlPod_add_constructor(CFCPerlPod *s
const char *initializer, const char *sample,
const char *pod);
+/** Generate POD for a METHODS section and possibly an ABSTRACT METHODS
+ * section as well.
+ */
char*
CFCPerlPod_methods_pod(CFCPerlPod *self, struct CFCClass *klass);
+/** Generate POD for a CONSTRUCTORS section.
+ */
char*
CFCPerlPod_constructors_pod(CFCPerlPod *self, struct CFCClass *klass);
+/** Supply a SYNOPSIS section.
+ */
void
CFCPerlPod_set_synopsis(CFCPerlPod *self, const char *synopsis);
+/** Accessor for SYNOPSIS text.
+ */
const char*
CFCPerlPod_get_synopsis(CFCPerlPod *self);
+/** Supply a DESCRIPTION section.
+ */
void
CFCPerlPod_set_description(CFCPerlPod *self, const char *description);
+/** Accessor for DESCRIPTION text.
+ */
const char*
CFCPerlPod_get_description(CFCPerlPod *self);
char*
CFCPerlPod_perlify_doc_text(CFCPerlPod *self, const char *source);
+/** Autogenerate pod for either a Clownfish::CFC::Method or a
+ * Clownfish::CFC::Function.
+ *
+ * @param func The Method or Function.
+ * @param alias The Perl name for the subroutine.
+ * @param klass The Clownfish::CFC::Class.
+ * @param code_sample Optional example usage code.
+ * @param is_construtor Indicate whether this is a constructor, as the default
+ * argument handling is different for constructors.
+ */
char*
CFCPerlPod_gen_subroutine_pod(CFCPerlPod *self, struct CFCFunction *func,
- const char *sub_name, struct CFCClass *klass,
+ const char *alias, struct CFCClass *klass,
const char *code_sample,
const char *class_name, int is_constructor);
Modified: incubator/lucy/trunk/clownfish/src/CFCPerlSub.h
URL:
http://svn.apache.org/viewvc/incubator/lucy/trunk/clownfish/src/CFCPerlSub.h?rev=1300388&r1=1300387&r2=1300388&view=diff
==============================================================================
--- incubator/lucy/trunk/clownfish/src/CFCPerlSub.h (original)
+++ incubator/lucy/trunk/clownfish/src/CFCPerlSub.h Tue Mar 13 22:44:28 2012
@@ -71,24 +71,29 @@ CFCPerlSub_destroy(CFCPerlSub *self);
char*
CFCPerlSub_params_hash_def(CFCPerlSub *self);
+/** Generate code which will invoke XSBind_allot_params() to parse labeled
+ * parameters supplied to an XSUB.
+ */
char*
CFCPerlSub_build_allot_params(CFCPerlSub *self);
+/** Accessor for param list.
+ */
struct CFCParamList*
CFCPerlSub_get_param_list(CFCPerlSub *self);
-/** Accessor.
+/** Accessor for class name.
*/
const char*
CFCPerlSub_get_class_name(CFCPerlSub *self);
-/** Accessor.
+/** Accessor for use_labeled_params.
*/
int
CFCPerlSub_use_labeled_params(CFCPerlSub *self);
/**
- * @return the fully-qualified perl sub name.
+ * @return the fully-qualified perl subroutine name.
*/
const char*
CFCPerlSub_perl_name(CFCPerlSub *self);
