clean up documents

move FML::String to Dialect::ISO2022JP (Dialect::Japanese::String)

3 files changed, 131 insertions, 27 deletions

diff --git a/fml/lib/IO/Adapter/File.pm b/fml/lib/IO/Adapter/File.pm
index a6b16c8f..ef2e4c85 100644
--- a/fml/lib/IO/Adapter/File.pm
+++ b/fml/lib/IO/Adapter/File.pm
@@ -14,6 +14,33 @@ use strict;
 use vars qw(@ISA @EXPORT @EXPORT_OK $AUTOLOAD);
 use Carp;
 
+=head1 NAME
+
+IO::Adapter::File - functions to do IO for a file
+
+=head1 SYNOPSIS
+
+    $map = 'file:/some/where/file';
+
+    use IO::MapAdapter;
+    $obj = new IO::MapAdapter $map;
+    $obj->open || croak("cannot open $map");
+    while ($x = $obj->getline) { ... }
+    $obj->close;
+
+=head1 DESCRIPTION
+
+This module provides real IO functions for a file used in IO::MapAdapter.
+The map is the fully pathed file name or a file name 'file:/' prefix.
+
+=head1 METHODS
+
+=head2 C<new()>
+
+standard constructor
+
+=cut
+
 
 sub new
 {
@@ -24,6 +51,15 @@ sub new
 }
 
 
+=head2 C<open($args)>
+
+$args HASH REFERENCE has two parameters. 
+C<file> is the target file to open.
+C<flag> is the mode of open().
+
+=cut
+
+
 sub open
 {
     my ($self, $args) = @_;
@@ -50,6 +86,19 @@ my $ec = 0;
 sub line_count { my ($self) = @_; return "${ec}/${c}";}
 
 
+=head2 C<getline()>
+
+return one line.
+It is the same as usual getline() call for a file.
+
+=head2 C<get_next_value()>
+
+return one line suitable with C<fml> IO design.
+This is used in C<fml5>.
+
+=cut
+
+
 sub getline
 {
     my ($self) = @_;
@@ -90,6 +139,17 @@ sub get_next_value
 }
 
 
+=head2 C<getpos()>
+
+get the position in the opened file.
+
+=head2 C<setpos(pos)>
+
+set the position in the opened file.
+
+=cut
+
+
 sub getpos
 {
     my ($self) = @_;
@@ -106,6 +166,17 @@ sub setpos
 }
 
 
+=head2 C<eof()>
+
+Eof Of File?
+
+=head2 C<close()>
+
+close the opended file.
+
+=cut
+
+
 sub eof
 {
     my ($self) = @_;
@@ -121,21 +192,9 @@ sub close
 }
 
 
-=head1 NAME
-
-IO::Adapter::File.pm - what is this
-
-=head1 SYNOPSIS
-
-=head1 DESCRIPTION
-
-=head1 CLASSES
-
-=head1 METHODS
-
-=item C<new()>
+=head1 SEE ALSO
 
-... what is this ...
+L<IO::MapAdapter>
 
 =head1 AUTHOR
 
diff --git a/fml/lib/IO/Adapter/LDAP.pm b/fml/lib/IO/Adapter/LDAP.pm
index ff68b365..237c6018 100644
--- a/fml/lib/IO/Adapter/LDAP.pm
+++ b/fml/lib/IO/Adapter/LDAP.pm
@@ -33,19 +33,15 @@ sub new
 
 =head1 NAME
 
-IO::Adapter::LDAP.pm - what is this
+IO::Adapter::LDAP - IO by LDAP
 
 =head1 SYNOPSIS
 
-=head1 DESCRIPTION
-
-=head1 CLASSES
+not yet implemented
 
-=head1 METHODS
-
-=item C<new()>
+=head1 DESCRIPTION
 
-... what is this ...
+not yet
 
 =head1 AUTHOR
 
diff --git a/fml/lib/IO/File/Atomic.pm b/fml/lib/IO/File/Atomic.pm
index ed2d06f6..f6bbb093 100644
--- a/fml/lib/IO/File/Atomic.pm
+++ b/fml/lib/IO/File/Atomic.pm
@@ -22,16 +22,16 @@ END   {}
 
 =head1 NAME
 
-IO::Atomic - atomic  operation
+IO::Atomic - atomic IO operation
 
 =head1 SYNOPSIS
 
     use IO::Atomic;
     my $wh = IO::Atomic->open($file);
     print $wh "new/updated things ...";
-    $wh->close;
+    $wh->close unless $wh->error;
 
-So, in usual cases, you use in this way.
+So, in usual cases, you use this module in the following way.
 
     use FileHandle;
     use IO::Atomic;
@@ -43,7 +43,7 @@ So, in usual cases, you use in this way.
     my $wh = IO::Atomic->open($file);
     while (<$rh>) {
         print $wh "new/updated things ...";
-    } 
+    }
     $wh->close;
     $rh->close;
 
@@ -65,7 +65,14 @@ To copy from $src to $dst,
 =head1 DESCRIPTION
 
 library to wrap atomic IO operations. 
-The C<atomic> feature is based on C<rename()> call.
+The C<atomic> feature is based on C<rename(2)> system call.
+
+=head1 METHODS
+
+=head2 C<new()>
+
+The usual constructor. 
+The request is forwarded to SUPERCLASS new().
 
 =cut
 
@@ -84,6 +91,29 @@ sub new
 }
 
 
+=head2 C<open(file[, mode])>
+
+open C<file> with C<mode>. 
+If C<mode> is not specified, open C<file> with writable mode by default.
+
+Actually this method openes a new temporary file for write.
+So to write this C<file> is to write the temporary file.
+When close() method sucesses, the file is replaced with this temporary file,
+so updated.
+
+=head2 C<rw_open(file[, mode])>
+
+return the read and write file descriptor. 
+This is a wrapper for C<open()> method above for conveninece.
+
+=head2 C<close()>
+
+close the file.
+After the file is closed, the file is renamed to the original file name.
+
+=cut
+
+
 # Descriptions: open( $file [, $mode] )
 #               open not $file but file.new.$$
 #               forward open() request to IO::File class
@@ -156,6 +186,14 @@ sub close
 }
 
 
+=head2 C<copy(src, dst)>
+
+copy from C<src> file to C<dst> file in atomic way by using 
+C<IO::File::Atomic::rw_open>.
+
+=cut
+
+
 # Descriptions: copy file, which ensures atomic operation
 #    Arguments: $self source_file destination_file
 # Side Effects: $dst's file mode becomes the same as $src
@@ -181,6 +219,17 @@ sub copy
 }
 
 
+=head2 C<error()>
+
+return the error.
+
+=head2 C<rollback()>
+
+stop the operation. remove the temporary file.
+
+=cut
+
+
 # Descriptions: return error message
 #    Arguments: $self
 #               XXX $self is blessed file handle.