Author: creamyg
Date: 2008-08-06 13:21:58 -0700 (Wed, 06 Aug 2008)
New Revision: 3728
Modified:
trunk/c_src/KinoSearch/InvIndex.bp
trunk/perl/lib/KinoSearch/InvIndex.pm
Log:
Port InvIndex docs to C. Sort of. The .bp file is coherent, but the
auto-generated POD is now glitchy, since Boilerplater::Binding::Perl can't
deal with multiple constructors.
Modified: trunk/c_src/KinoSearch/InvIndex.bp
===================================================================
--- trunk/c_src/KinoSearch/InvIndex.bp 2008-08-06 19:37:36 UTC (rev 3727)
+++ trunk/c_src/KinoSearch/InvIndex.bp 2008-08-06 20:21:58 UTC (rev 3728)
@@ -1,25 +1,71 @@
parcel KinoSearch cnick Kino;
+/** An inverted index.
+ *
+ * "InvIndex" is short for "inverted index", the name for the data structure
+ * which KinoSearch is based around. Generically, an inverted index, as opposed
+ * to any other kind of index, contains mappings from keywords to documents,
+ * allowing you to look up a term and find out where it occurs within a
+ * collection.
+ *
+ * A KinoSearch::InvIndex object has two main parts: a
+ * L<Schema|KinoSearch::Schema> and a L<Folder|KinoSearch::Store::Folder>. The
+ * Schema describes how the index data is structured, and the Folder provides the
+ * I/O capabilities for actually getting at the data and doing something with it.
+ *
+ * InvIndex provides three constructors: clobber(), open(), and read(), which are
+ * usually invoked internally via factory methods from Schema. However, when
+ * called directly, InvIndex's constructors allow you more flexibility in
+ * supplying the <code>folder</code> argument, so you can do things like supply a
+ * L<RAMFolder|KinoSearch::Store::RAMFolder>.
+ */
class KinoSearch::InvIndex extends KinoSearch::Obj {
Schema *schema;
Folder *folder;
+ /**
+ * @param schema A KinoSearch::Schema.
+ * @param folder Either a KinoSearch::Store::Folder or a string filepath.
+ */
static InvIndex*
init(InvIndex *self, Schema *schema, Obj *folder);
+ /** Open an invindex for either reading or updating. Fails if the
+ * invindex doesn't exist.
+ *
+ * @param schema A KinoSearch::Schema.
+ * @param folder Either a KinoSearch::Store::Folder or a string filepath.
+ */
static InvIndex*
read(InvIndex *self, Schema *schema, Obj *folder);
+ /** Open an invindex for reading/writing. Initializes a new invindex if
+ * one does not already exist.
+ *
+ * @param schema A KinoSearch::Schema.
+ * @param folder Either a KinoSearch::Store::Folder or a string filepath.
+ */
static InvIndex*
open(InvIndex *self, Schema *schema, Obj *folder);
+ /** Initialize a new invindex, creating a directory on the file system if
+ * appropriate. Attempts to delete any files within the Folder that look
+ * like index files.
+ *
+ * @param schema A KinoSearch::Schema.
+ * @param folder Either a KinoSearch::Store::Folder or a string filepath.
+ */
static InvIndex*
clobber(InvIndex *self, Schema *schema, Obj *folder);
+ /** Accessor.
+ */
Schema*
Get_Schema(InvIndex *self);
+ /** Accessor.
+ */
Folder*
Get_Folder(InvIndex *self);
Modified: trunk/perl/lib/KinoSearch/InvIndex.pm
===================================================================
--- trunk/perl/lib/KinoSearch/InvIndex.pm 2008-08-06 19:37:36 UTC (rev 3727)
+++ trunk/perl/lib/KinoSearch/InvIndex.pm 2008-08-06 20:21:58 UTC (rev 3728)
@@ -6,119 +6,53 @@
__AUTO_XS__
-{ "KinoSearch::InvIndex" => {
- bind_methods => [qw( get_schema get_folder )],
- make_constructors => [qw( read|read open|open clobber|clobber )],
- }
-}
-
-__POD__
-
-=head1 NAME
-
-KinoSearch::InvIndex - An inverted index.
-
-=head1 SYNOPSIS
-
- use MySchema;
+my $synopsis = <<'END_SYNOPSIS';
my $invindex = MySchema->clobber('/path/to/invindex');
-
-=head1 DESCRIPTION
-
-"InvIndex" is short for "inverted index", the name for the data structure
-which KinoSearch is based around. Generically, an inverted index, as opposed
-to any other kind of index, contains mappings from keywords to documents,
-allowing you to look up a term and find out where it occurs within a
-collection.
-
-A KinoSearch::InvIndex object has two main parts: a
-L<Schema|KinoSearch::Schema> and a L<Folder|KinoSearch::Store::Folder>. The
-Schema describes how the index data is structured, and the Folder provides the
-I/O capabilities for actually getting at the data and doing something with it.
-
-=head1 CONSTRUCTORS
-
-InvIndex provides three constructors: clobber(), open(), and read(). They
-all take hash-style params.
-
-=over
-
-=item *
-
-B<schema> - An object which isa KinoSearch::Schema.
-
-=item *
-
-B<folder> - Either an object which isa L<KinoSearch::Store::Folder>, or a
-filepath. If a filepath is supplied, an
-L<FSFolder|KinoSearch::Store::FSFolder> object will be created.
-
-=item *
-
-B<lock_factory> - [Optional] An object which isa
-L<LockFactory|KinoSearch::Store::LockFactory>. If not supplied, a LockFactory
-will be created for use by clobber() and open() during index initialization.
-
-=back
-
-These constructors are usually called via factory methods from Schema:
-
- my $invindex = MySchema->clobber($filepath);
-
- # ... is the same as...
-
+
+ # ... which is equivalent to:
+ my $folder = KinoSearch::Store::FSFolder->new(
+ path => '/path/to/invindex',
+ );
my $invindex = KinoSearch::InvIndex->clobber(
schema => MySchema->new,
- folder => KinoSearch::Store::FSFolder->new( path => $filepath ),
+ folder => $folder,
);
+END_SYNOPSIS
-However, when called directly, InvIndex's constructors allow you more
-flexibility in supplying the C<folder> argument, so you can do things like
-supply a L<RAMFolder|KinoSearch::Store::RAMFolder>.
-
-=head2 clobber
-
+my $constructor_sample = <<'END_CONSTRUCTOR';
my $invindex = KinoSearch::InvIndex->clobber(
- schema => MySchema->new,
- folder => $path_or_folder_obj,
+ schema => $schema,
+ folder => $folder,
);
-
-Initialize a new invindex, creating a directory on the file system if
-appropriate. Attempts to delete any files within the Folder that look like
-index files.
-
-=head2 open
-
+
+ # or...
my $invindex = KinoSearch::InvIndex->open(
- schema => MySchema->new,
- folder => $path_or_folder_obj,
+ schema => $schema,
+ folder => $folder,
);
-
-Open an invindex for reading/writing. Initializes a new invindex if one does
-not already exist.
-
-=head2 read
-
+
+ # or...
my $invindex = KinoSearch::InvIndex->read(
- schema => MySchema->new,
- folder => $path_or_folder_obj,
+ schema => $schema,
+ folder => $folder,
);
+END_CONSTRUCTOR
-Open an invindex for either reading or updating. Fails if the invindex
-doesn't exist.
+{ "KinoSearch::InvIndex" => {
+ bind_methods => [qw( get_schema get_folder )],
+ make_constructors => [qw( read|read open|open clobber|clobber )],
+ make_pod => {
+ constructor => { sample => $constructor_sample },
+ synopsis => $synopsis,
+ methods => [qw( get_schema get_folder )],
+ }
+ }
+}
-=head1 METHODS
+__COPYRIGHT__
-=head2 get_folder get_invindex
+Copyright 2005-2008 Marvin Humphrey
-Getters for folder and invindex.
+This program is free software; you can redistribute it and/or modify
+under the same terms as Perl itself.
-=head1 COPYRIGHT
-
-Copyright 2007-2008 Marvin Humphrey
-
-=head1 LICENSE, DISCLAIMER, BUGS, etc.
-
-See L<KinoSearch> version 0.20.
-
-=cut
_______________________________________________
kinosearch-commits mailing list
kinosearch-commits@rectangular.com
http://www.rectangular.com/mailman/listinfo/kinosearch-commits
Date: 2008-08-06 13:21:58 -0700 (Wed, 06 Aug 2008)
New Revision: 3728
Modified:
trunk/c_src/KinoSearch/InvIndex.bp
trunk/perl/lib/KinoSearch/InvIndex.pm
Log:
Port InvIndex docs to C. Sort of. The .bp file is coherent, but the
auto-generated POD is now glitchy, since Boilerplater::Binding::Perl can't
deal with multiple constructors.
Modified: trunk/c_src/KinoSearch/InvIndex.bp
===================================================================
--- trunk/c_src/KinoSearch/InvIndex.bp 2008-08-06 19:37:36 UTC (rev 3727)
+++ trunk/c_src/KinoSearch/InvIndex.bp 2008-08-06 20:21:58 UTC (rev 3728)
@@ -1,25 +1,71 @@
parcel KinoSearch cnick Kino;
+/** An inverted index.
+ *
+ * "InvIndex" is short for "inverted index", the name for the data structure
+ * which KinoSearch is based around. Generically, an inverted index, as opposed
+ * to any other kind of index, contains mappings from keywords to documents,
+ * allowing you to look up a term and find out where it occurs within a
+ * collection.
+ *
+ * A KinoSearch::InvIndex object has two main parts: a
+ * L<Schema|KinoSearch::Schema> and a L<Folder|KinoSearch::Store::Folder>. The
+ * Schema describes how the index data is structured, and the Folder provides the
+ * I/O capabilities for actually getting at the data and doing something with it.
+ *
+ * InvIndex provides three constructors: clobber(), open(), and read(), which are
+ * usually invoked internally via factory methods from Schema. However, when
+ * called directly, InvIndex's constructors allow you more flexibility in
+ * supplying the <code>folder</code> argument, so you can do things like supply a
+ * L<RAMFolder|KinoSearch::Store::RAMFolder>.
+ */
class KinoSearch::InvIndex extends KinoSearch::Obj {
Schema *schema;
Folder *folder;
+ /**
+ * @param schema A KinoSearch::Schema.
+ * @param folder Either a KinoSearch::Store::Folder or a string filepath.
+ */
static InvIndex*
init(InvIndex *self, Schema *schema, Obj *folder);
+ /** Open an invindex for either reading or updating. Fails if the
+ * invindex doesn't exist.
+ *
+ * @param schema A KinoSearch::Schema.
+ * @param folder Either a KinoSearch::Store::Folder or a string filepath.
+ */
static InvIndex*
read(InvIndex *self, Schema *schema, Obj *folder);
+ /** Open an invindex for reading/writing. Initializes a new invindex if
+ * one does not already exist.
+ *
+ * @param schema A KinoSearch::Schema.
+ * @param folder Either a KinoSearch::Store::Folder or a string filepath.
+ */
static InvIndex*
open(InvIndex *self, Schema *schema, Obj *folder);
+ /** Initialize a new invindex, creating a directory on the file system if
+ * appropriate. Attempts to delete any files within the Folder that look
+ * like index files.
+ *
+ * @param schema A KinoSearch::Schema.
+ * @param folder Either a KinoSearch::Store::Folder or a string filepath.
+ */
static InvIndex*
clobber(InvIndex *self, Schema *schema, Obj *folder);
+ /** Accessor.
+ */
Schema*
Get_Schema(InvIndex *self);
+ /** Accessor.
+ */
Folder*
Get_Folder(InvIndex *self);
Modified: trunk/perl/lib/KinoSearch/InvIndex.pm
===================================================================
--- trunk/perl/lib/KinoSearch/InvIndex.pm 2008-08-06 19:37:36 UTC (rev 3727)
+++ trunk/perl/lib/KinoSearch/InvIndex.pm 2008-08-06 20:21:58 UTC (rev 3728)
@@ -6,119 +6,53 @@
__AUTO_XS__
-{ "KinoSearch::InvIndex" => {
- bind_methods => [qw( get_schema get_folder )],
- make_constructors => [qw( read|read open|open clobber|clobber )],
- }
-}
-
-__POD__
-
-=head1 NAME
-
-KinoSearch::InvIndex - An inverted index.
-
-=head1 SYNOPSIS
-
- use MySchema;
+my $synopsis = <<'END_SYNOPSIS';
my $invindex = MySchema->clobber('/path/to/invindex');
-
-=head1 DESCRIPTION
-
-"InvIndex" is short for "inverted index", the name for the data structure
-which KinoSearch is based around. Generically, an inverted index, as opposed
-to any other kind of index, contains mappings from keywords to documents,
-allowing you to look up a term and find out where it occurs within a
-collection.
-
-A KinoSearch::InvIndex object has two main parts: a
-L<Schema|KinoSearch::Schema> and a L<Folder|KinoSearch::Store::Folder>. The
-Schema describes how the index data is structured, and the Folder provides the
-I/O capabilities for actually getting at the data and doing something with it.
-
-=head1 CONSTRUCTORS
-
-InvIndex provides three constructors: clobber(), open(), and read(). They
-all take hash-style params.
-
-=over
-
-=item *
-
-B<schema> - An object which isa KinoSearch::Schema.
-
-=item *
-
-B<folder> - Either an object which isa L<KinoSearch::Store::Folder>, or a
-filepath. If a filepath is supplied, an
-L<FSFolder|KinoSearch::Store::FSFolder> object will be created.
-
-=item *
-
-B<lock_factory> - [Optional] An object which isa
-L<LockFactory|KinoSearch::Store::LockFactory>. If not supplied, a LockFactory
-will be created for use by clobber() and open() during index initialization.
-
-=back
-
-These constructors are usually called via factory methods from Schema:
-
- my $invindex = MySchema->clobber($filepath);
-
- # ... is the same as...
-
+
+ # ... which is equivalent to:
+ my $folder = KinoSearch::Store::FSFolder->new(
+ path => '/path/to/invindex',
+ );
my $invindex = KinoSearch::InvIndex->clobber(
schema => MySchema->new,
- folder => KinoSearch::Store::FSFolder->new( path => $filepath ),
+ folder => $folder,
);
+END_SYNOPSIS
-However, when called directly, InvIndex's constructors allow you more
-flexibility in supplying the C<folder> argument, so you can do things like
-supply a L<RAMFolder|KinoSearch::Store::RAMFolder>.
-
-=head2 clobber
-
+my $constructor_sample = <<'END_CONSTRUCTOR';
my $invindex = KinoSearch::InvIndex->clobber(
- schema => MySchema->new,
- folder => $path_or_folder_obj,
+ schema => $schema,
+ folder => $folder,
);
-
-Initialize a new invindex, creating a directory on the file system if
-appropriate. Attempts to delete any files within the Folder that look like
-index files.
-
-=head2 open
-
+
+ # or...
my $invindex = KinoSearch::InvIndex->open(
- schema => MySchema->new,
- folder => $path_or_folder_obj,
+ schema => $schema,
+ folder => $folder,
);
-
-Open an invindex for reading/writing. Initializes a new invindex if one does
-not already exist.
-
-=head2 read
-
+
+ # or...
my $invindex = KinoSearch::InvIndex->read(
- schema => MySchema->new,
- folder => $path_or_folder_obj,
+ schema => $schema,
+ folder => $folder,
);
+END_CONSTRUCTOR
-Open an invindex for either reading or updating. Fails if the invindex
-doesn't exist.
+{ "KinoSearch::InvIndex" => {
+ bind_methods => [qw( get_schema get_folder )],
+ make_constructors => [qw( read|read open|open clobber|clobber )],
+ make_pod => {
+ constructor => { sample => $constructor_sample },
+ synopsis => $synopsis,
+ methods => [qw( get_schema get_folder )],
+ }
+ }
+}
-=head1 METHODS
+__COPYRIGHT__
-=head2 get_folder get_invindex
+Copyright 2005-2008 Marvin Humphrey
-Getters for folder and invindex.
+This program is free software; you can redistribute it and/or modify
+under the same terms as Perl itself.
-=head1 COPYRIGHT
-
-Copyright 2007-2008 Marvin Humphrey
-
-=head1 LICENSE, DISCLAIMER, BUGS, etc.
-
-See L<KinoSearch> version 0.20.
-
-=cut
_______________________________________________
kinosearch-commits mailing list
kinosearch-commits@rectangular.com
http://www.rectangular.com/mailman/listinfo/kinosearch-commits