git commit: Fix documentation of Clownfish::CFC::Perl::Build

[nw...@apache.org]

Repository: lucy-clownfish
Updated Branches:
  refs/heads/master 9150ca3ae -> f03f8adb0


Fix documentation of Clownfish::CFC::Perl::Build


Project: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/commit/f03f8adb
Tree: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/tree/f03f8adb
Diff: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/diff/f03f8adb

Branch: refs/heads/master
Commit: f03f8adb06bbe5402adaabadba73ed04818ee171
Parents: 9150ca3
Author: Nick Wellnhofer <we...@aevum.de>
Authored: Sun Jul 6 23:34:49 2014 +0200
Committer: Nick Wellnhofer <we...@aevum.de>
Committed: Sun Jul 6 23:49:43 2014 +0200

----------------------------------------------------------------------
 compiler/perl/lib/Clownfish/CFC/Perl/Build.pm | 112 +++++++++++++--------
 1 file changed, 69 insertions(+), 43 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/f03f8adb/compiler/perl/lib/Clownfish/CFC/Perl/Build.pm
----------------------------------------------------------------------
diff --git a/compiler/perl/lib/Clownfish/CFC/Perl/Build.pm b/compiler/perl/lib/Clownfish/CFC/Perl/Build.pm
index 6c94cf4..9a4091d 100644
--- a/compiler/perl/lib/Clownfish/CFC/Perl/Build.pm
+++ b/compiler/perl/lib/Clownfish/CFC/Perl/Build.pm
@@ -38,15 +38,13 @@ else {
     );
 }
 
-=for Rationale
+# Rationale
 
-When the distribution tarball for the Perl bindings is built, core/, and any
-other needed files/directories are copied into the perl/ directory within the
-main source directory.  Then the distro is built from the contents of the
-perl/ directory, leaving out all the files in ruby/, etc. However, during
-development, the files are accessed from their original locations.
-
-=cut
+# When the distribution tarball for the Perl bindings is built, core/, and any
+# other needed files/directories are copied into the perl/ directory within the
+# main source directory.  Then the distro is built from the contents of the
+# perl/ directory, leaving out all the files in ruby/, etc. However, during
+# development, the files are accessed from their original locations.
 
 my @BASE_PATH;
 push(@BASE_PATH, updir()) unless -e 'core';
@@ -557,7 +555,7 @@ __END__
 
 =head1 NAME
 
-Clownfish::CFC::Perl::Build - Build Clownfish modules
+Clownfish::CFC::Perl::Build - Build Clownfish modules.
 
 =head1 DESCRIPTION
 
@@ -601,72 +599,100 @@ the Perl bindings for Clownfish modules.
 
 =head1 CONSTRUCTOR
 
-=head2 my $builder = Clownfish::CFC::Perl::Build->new(%args);
+=head2 new( I<[labeled params]> )
 
-Creates a new Clownfish::CFC::Perl::Build object. %args can contain all
-arguments that can be passed to L<Module::Build/new>. It accepts an additional
-argument 'clownfish_params', which is a hashref with the following params:
+    my $builder = Clownfish::CFC::Perl::Build->new(%args);
 
-=head3 source
+Creates a new Clownfish::CFC::Perl::Build object. C<%args> can contain all
+arguments that can be passed to L<Module::Build::API/new>. It accepts an
+additional argument C<clownfish_params> which is a hashref with the following
+params:
 
-An arrayref of source directories containing the .cfh and .c files of the
-module. Defaults to [ 'core' ] or to [ '../core' ] if 'core' can't
-be found.
+=over
 
-=head3 include
+=item *
 
-An arrayref of include directories containing .cfh files from other Clownfish
-modules needed by the module. Empty by default. Should contain the Clownfish
-system include directories if needed.
+B<source> - An arrayref of source directories containing the .cfh and .c files
+of the module. Defaults to C<[ 'core' ]> or to C<[ '../core' ]> if C<core>
+can't be found.
 
-=head3 autogen_header
+=item *
 
-A string that will be prepended to the files generated by the Clownfish
-compiler.
+B<include> - An arrayref of include directories containing .cfh files from
+other Clownfish modules needed by the module. Empty by default. Should contain
+the Clownfish system include directories if needed.
 
-=head3 cflags
+=item *
 
-A string with additional compiler flags used to compile the Clownfish .c
-files.
+B<autogen_header> - A string that will be prepended to the files generated by
+the Clownfish compiler.
 
-=head1 METHODS
+=item *
 
-=head2 my @path = Clownfish::CFC::Perl::Build->cf_base_path();
+B<cflags> - A string with additional compiler flags used to compile the
+Clownfish .c files.
 
-Returns the base path of the source tree where 'core' etc. will be found.
-Currently either () or ('..').
+=back
 
-=head1 METHODS
+=head1 CLASS METHODS
+
+=head2 cf_base_path()
 
-=head2 my @dirs = Clownfish::CFC::Perl::Build->cf_system_include_dirs();
+    my @path = Clownfish::CFC::Perl::Build->cf_base_path();
+
+Returns the base path components of the source tree where C<core> was found.
+Currently either C<()> or C<('..')>.
+
+=head2 cf_system_include_dirs()
+
+    my @dirs = Clownfish::CFC::Perl::Build->cf_system_include_dirs();
 
 Returns a list of Clownfish include directories of system-wide installations
 of Clownfish modules.
 
-=head2 my @flags = Clownfish::CFC::Perl::Build->cf_linker_flags($module_name);
+=head2 cf_linker_flags(module_name)
+
+    my @flags = Clownfish::CFC::Perl::Build->cf_linker_flags($module_name);
 
 Returns the linker flags needed to link against Clownfish module named
-$module_name. Should be added to extra_linker_flags for all module
+C<$module_name>. Should be added to C<extra_linker_flags> for all module
 dependencies.
 
-=head2 $builder->cf_copy_include_file(@path);
+=head1 METHODS
 
-Look for a file with path components @path in all of the Module::Build
-include dirs and copy it to blib, so it will be installed in a Clownfish
+=head2 cf_copy_include_file( I<[path components]> )
+
+    $builder->cf_copy_include_file(@path);
+
+Look for a file with path components C<@path> in all of the Module::Build
+include dirs and copy it to C<blib>, so it will be installed in a Clownfish
 system include directory. Typically used for additional .h files that the
 .cfh files need.
 
-=head2 my $value = $builder->clownfish_params($key);
+=head2 clownfish_params()
+
+    my $value = $builder->clownfish_params($key);
 
-=head2 $builder->clownfish_params($key => $value);
+    $builder->clownfish_params($key => $value);
 
 Get or set a Clownfish build param. Supports all the parameters that can be
 passed to L</new>.
 
-=head1 COPYRIGHT
+=head1 BUILD ACTIONS
+
+Clownfish::CFC::Perl::Build defines the following build actions.
+
+=head2 code
+
+Build the whole project.
+
+=head2 clownfish
+
+Compile the Clownfish headers and generate code in the C<autogen> directory.
+
+=head2 pod
 
-Clownfish is distributed under the Apache License, Version 2.0, as
-described in the file C<LICENSE> included with the distribution.
+Generate POD from Clownfish headers.
 
 =cut