From c0f3e6ac4d3b810dc2b6c92a80a74d8a6b04ce9b Mon Sep 17 00:00:00 2001
From: Jesse Luehrs <doy@tozt.net>
Date: Fri, 19 Feb 2010 17:13:54 -0600
Subject: add docs

---
 lib/Locale/POFileManager.pm      | 54 ++++++++++++++++++++++++++++++++++++++++
 lib/Locale/POFileManager/File.pm | 42 +++++++++++++++++++++++++++++++
 2 files changed, 96 insertions(+)

diff --git a/lib/Locale/POFileManager.pm b/lib/Locale/POFileManager.pm
index 2ce4357..b32b076 100644
--- a/lib/Locale/POFileManager.pm
+++ b/lib/Locale/POFileManager.pm
@@ -33,10 +33,34 @@ the L<Locale::PO> parser library.
 
 =head2 new
 
+Accepts a hash of arguments:
+
+=over 4
+
+=item base_dir
+
+The directory that contains the .po files. Required.
+
+=item canonical_language
+
+The language for the file that contains the canonical set of msgids. Required.
+
+=item stub_msgstr
+
+The msgstr to insert when adding stubs to language files. This can be either a
+literal string, or a coderef which accepts a hash containing the keys C<msgid>,
+C<lang>, and C<canonical_msgstr> (the msgstr value from the
+C<canonical_language>. Optional.
+
+=back
+
 =cut
 
 =head2 base_dir
 
+Returns a L<Path::Class::Dir> object corresponding to the C<base_dir> passed to
+the constructor.
+
 =cut
 
 has base_dir => (
@@ -48,6 +72,9 @@ has base_dir => (
 
 =head2 files
 
+Returns a list of L<Locale::POFileManager::File> objects corresponding to the
+.po files that were found in the C<base_dir>.
+
 =cut
 
 has files => (
@@ -85,6 +112,8 @@ sub _build_files {
 
 =head2 canonical_language
 
+Returns the canonical language id passed to the constructor.
+
 =cut
 
 has canonical_language => (
@@ -108,6 +137,10 @@ sub BUILD {
 
 =head2 stub_msgstr
 
+Returns the string passed to the constructor as C<stub_msgstr> if it was a
+string, or a coderef wrapped to supply the C<canonical_msgstr> option if it was
+a coderef.
+
 =cut
 
 sub stub_msgstr {
@@ -133,6 +166,9 @@ sub stub_msgstr {
 
 =head2 has_language
 
+Returns true if a language file exists for the given language in the
+C<base_dir>, false otherwise.
+
 =cut
 
 sub has_language {
@@ -148,6 +184,10 @@ sub has_language {
 
 =head2 add_language
 
+Creates a new language file for the language passed in as an argument. Creates
+a header for that file copied over from the header in the C<canonical_language>
+language file, and saves the newly created file in the C<base_dir>.
+
 =cut
 
 sub add_language {
@@ -173,6 +213,9 @@ sub add_language {
 
 =head2 language_file
 
+Returns the L<Locale::POFileManager> object corresponding to the given
+language.
+
 =cut
 
 sub language_file {
@@ -186,6 +229,9 @@ sub language_file {
 
 =head2 canonical_language_file
 
+Returns the L<Locale::POFileManager> object corresponding to the
+C<canonical_language>.
+
 =cut
 
 sub canonical_language_file {
@@ -195,6 +241,10 @@ sub canonical_language_file {
 
 =head2 find_missing
 
+Searches through all of the files in the C<base_dir>, and returns a hash
+mapping language names to an arrayref of msgids that were found in the
+C<canonical_language> file but not in the file for that language.
+
 =cut
 
 sub find_missing {
@@ -211,6 +261,10 @@ sub find_missing {
 
 =head2 add_stubs
 
+Adds stub msgid (and possibly msgstr, if the C<stub_msgstr> option was given)
+entries to each language file for each msgid found in the C<canonical_language>
+file but not in the language file.
+
 =cut
 
 sub add_stubs {
diff --git a/lib/Locale/POFileManager/File.pm b/lib/Locale/POFileManager/File.pm
index e5e8267..7e7fc3d 100644
--- a/lib/Locale/POFileManager/File.pm
+++ b/lib/Locale/POFileManager/File.pm
@@ -40,10 +40,27 @@ manipulating the translation entries in it.
 
 =head2 new
 
+Accepts a hash of arguments:
+
+=over 4
+
+=item file
+
+The name of the file this represents. Required.
+
+=item stub_msgstr
+
+The msgstr to insert when adding stubs to language files. This can be either a
+literal string, or a coderef which accepts a hash containing the keys C<msgid>
+and C<lang>. Optional.
+
 =cut
 
 =head2 file
 
+Returns a L<Path::Class::File> object corresponding to the C<file> passed to
+the constructor.
+
 =cut
 
 has file => (
@@ -55,6 +72,8 @@ has file => (
 
 =head2 stub_msgstr
 
+Returns the C<stub_msgstr> passed to the constructor.
+
 =cut
 
 has stub_msgstr => (
@@ -64,14 +83,23 @@ has stub_msgstr => (
 
 =head2 entries
 
+Returns a list of L<Locale::PO> objects corresponding to translation entries in
+the file.
+
 =cut
 
 =head2 add_entry
 
+Adds a new translation entry to the file. This can be provided either as a
+L<Locale::PO> object directly, or as a hash of options to pass to the
+L<Locale::PO> constructor (except without the leading dashes).
+
 =cut
 
 =head2 msgids
 
+Returns a list of msgids found in the file.
+
 =cut
 
 has entries => (
@@ -109,6 +137,8 @@ sub add_entry {
 
 =head2 entry_for
 
+Returns the L<Locale::PO> object corresponding to the given msgid.
+
 =cut
 
 sub entry_for {
@@ -119,6 +149,8 @@ sub entry_for {
 
 =head2 save
 
+Writes the current contents of the file back out to disk.
+
 =cut
 
 sub save {
@@ -129,6 +161,8 @@ sub save {
 
 =head2 language
 
+Returns the language that this file corresponds to.
+
 =cut
 
 sub language {
@@ -140,6 +174,10 @@ sub language {
 
 =head2 find_missing_from
 
+Takes another translation file (either as a filename or as a
+L<Locale::POFileManager::File> object), and returns a list of msgids that the
+given file contains that this file doesn't.
+
 =cut
 
 sub find_missing_from {
@@ -158,6 +196,10 @@ sub find_missing_from {
 
 =head2 add_stubs_from
 
+Takes another translation file (either as a filename or as a
+L<Locale::POFileManager::File> object), and adds stubs for each msgid that the
+given file contains that this file doesn't.
+
 =cut
 
 sub add_stubs_from {
-- 
cgit v1.2.3