From 0cbef3716f8ecfc5fd40edc8b1e0e9770b8357df Mon Sep 17 00:00:00 2001
From: jluehrs2 <jluehrs2@uiuc.edu>
Date: Sat, 2 Feb 2008 18:42:23 -0500
Subject: add documentation to Games::Word::Wordlist

---
 lib/Games/Word/Wordlist.pm | 153 ++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 130 insertions(+), 23 deletions(-)

diff --git a/lib/Games/Word/Wordlist.pm b/lib/Games/Word/Wordlist.pm
index f5aa6d1..59e35e0 100644
--- a/lib/Games/Word/Wordlist.pm
+++ b/lib/Games/Word/Wordlist.pm
@@ -5,6 +5,58 @@ use warnings;
 use Games::Word qw/all_permutations is_subpermutation/;
 use List::MoreUtils qw/uniq/;
 
+=head1 NAME
+
+Games::Word::Wordlist - manages a list of words
+
+=head1 VERSION
+
+Version 0.01 released ???
+
+=cut
+
+our $VERSION = '0.01';
+
+=head1 SYNOPSIS
+
+    use Games::Word::Wordlist;
+    my $wl = Games::Word::Wordlist->new('/usr/share/dict/words');
+    my $word = $wl->random_word;
+    print "we have a word" if $wl->is_word($word);
+
+=head1 DESCRIPTION
+
+Games::Word::Wordlist manages a list of words, either from a wordlist file on
+your computer or from a list of words you specify. You can use it to query
+things about the list, such as whether a given string is a word, or how many
+words are in the list, and you can also get words from the list, either
+randomly or by regex.
+
+=cut
+
+=head1 CONSTRUCTOR
+
+=head2 new()
+
+The constructor initializes the word list with words, either from a file or
+from an arrayref, given as the first argument. The remaining arguments are a
+paramhash which recognizes these options:
+
+=over 4
+
+=item cache
+
+Whether or not we want to keep an in memory cache of the words in the word
+list. Defaults to true, since this is what we want in almost all cases, as it
+speeds up lookups by several orders of magnitude. Can be set to false if either
+memory is a significant issue (word lists can be several megabytes in size) or
+if the word list is expected to change frequently during the running of the
+program.
+
+=back
+
+=cut
+
 sub new {
     my $class = shift;
     my $word_list = shift;
@@ -40,6 +92,17 @@ sub new {
     return $self;
 }
 
+=head1 METHODS
+
+=head2 add_words
+
+Add words to the word list. Only works if the word list has been cached.
+
+Takes either a reference to an array containing the new words, or the name of a
+file to read in the words from. Ignores any words already in the word list.
+
+=cut
+
 sub add_words {
     my $self = shift;
     my $word_list = shift;
@@ -57,6 +120,14 @@ sub add_words {
     $self->{word_list} = [keys %{$self->{word_hash}}];
 }
 
+=head2 remove_words
+
+Removes words from the word list. Only works if the word list is cached.
+
+Takes a list of words to remove (ignoring words that aren't in the word list).
+
+=cut
+
 sub remove_words {
     my $self = shift;
 
@@ -64,6 +135,12 @@ sub remove_words {
     $self->{word_list} = [keys %{$self->{word_hash}}];
 }
 
+=head2 words
+
+Returns the number of words in the word list.
+
+=cut
+
 sub words {
     my $self = shift;
 
@@ -109,6 +186,15 @@ sub _random_word_nocache {
     return $word;
 }
 
+=head2 random_word
+
+Returns a random word from the word list, optionally of a specified length.
+
+Takes a single optional integer argument, which will make it only consider
+words of that length in its search.
+
+=cut
+
 sub random_word {
     my $self = shift;
 
@@ -137,6 +223,16 @@ sub _is_word_nocache {
     return 0;
 }
 
+=head2 is_word
+
+Tests whether a word is in the word list.
+
+Takes a single argument, the word to be tested.
+
+Returns true if the word is found in the word list, false otherwise.
+
+=cut
+
 sub is_word {
     my $self = shift;
 
@@ -170,6 +266,17 @@ sub _each_word {
     return $self->_each_word_nocache(@_);
 }
 
+=head2 anagrams
+
+Finds all anagrams of a given string.
+
+Takes an argument of a string.
+
+Returns a list of all permutations of that string that are found in the word
+list.
+
+=cut
+
 sub anagrams {
     my $self = shift;
     my $word = shift;
@@ -177,6 +284,16 @@ sub anagrams {
     return uniq grep { $self->is_word($_) } all_permutations($word);
 }
 
+=head2 words_like
+
+Searches through the word list by regex.
+
+Takes an argument of a regex.
+
+Returns a list containing all words in the word list matching that regex.
+
+=cut
+
 sub words_like {
     my $self = shift;
     my $re = shift;
@@ -187,6 +304,17 @@ sub words_like {
     return @words;
 }
 
+=head2 subwords_of
+
+Searches for words which can be made using the letters of a given string.
+
+Takes an argument of a string.
+
+Returns a list of words from the word list which can be made using the letters
+in that string.
+
+=cut
+
 sub subwords_of {
     my $self = shift;
     my $string = shift;
@@ -198,30 +326,9 @@ sub subwords_of {
     return @words;
 }
 
-=head1 NAME
-
-Games::Word::Wordlist - ???
-
-=head1 VERSION
-
-Version 0.01 released ???
-
-=cut
-
-our $VERSION = '0.01';
-
-=head1 SYNOPSIS
-
-    use Games::Word::Wordlist;
-    do_stuff();
-
-=head1 DESCRIPTION
-
-
-
 =head1 SEE ALSO
 
-L<Foo::Bar>
+L<Games::Word>
 
 =head1 AUTHOR
 
@@ -239,7 +346,7 @@ L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Games-Word>.
 
 You can find this documentation for this module with the perldoc command.
 
-    perldoc Games::Word
+    perldoc Games::Word::Wordlist
 
 You can also look for information at:
 
-- 
cgit v1.2.3