clean up documents

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

12 files changed, 208 insertions, 58 deletions

diff --git a/fml/lib/Dialect/ISO2022JP.pm b/fml/lib/Dialect/ISO2022JP.pm
index 4e67cfcc..f56f0615 100644
--- a/fml/lib/Dialect/ISO2022JP.pm
+++ b/fml/lib/Dialect/ISO2022JP.pm
@@ -13,11 +13,7 @@ package Dialect::ISO2022JP;
 use strict;
 use vars qw(@ISA @EXPORT @EXPORT_OK $AUTOLOAD);
 use Carp;
-use Dialect::Japanese::Utils qw(is_iso2022jp_string);
 
-require Exporter;
-@ISA       = qw(Dialect::Japanese::Utils Exporter);
-@EXPORT_OK = @Dialect::Japanese::Utils::EXPORT_OK;
 
 =head1 NAME
 
@@ -28,9 +24,35 @@ Dialect::ISO2022JP - adapter for Dialect::Japanese
     use Dialect::ISO2022JP qw(is_iso2022jp_string);
     if ( is_iso2022jp_string($string) ) { do_something_if_Japanese;}
 
+    use Dialect::ISO2022JP qw(STR2EUC);
+    $euc_string = STR2EUC( $string );
+
+=cut
+
+
+use Dialect::Japanese::Utils qw(is_iso2022jp_string);
+use Dialect::Japanese::String qw(STR2JIS STR2EUC STR2SJIS);
+
+require Exporter;
+@ISA = qw(Dialect::Japanese::Utils Dialect::Japanese::String Exporter);
+push(@EXPORT_OK, @Dialect::Japanese::Utils::EXPORT_OK);
+push(@EXPORT_OK, @Dialect::Japanese::String::EXPORT_OK);
+
+
+=head1 METHODS
+
+=head2 C<is_iso2022jp_string>
+
+See L<Dialect::Japanese::Utils>
+
+=head2 C<STR2JIS> C<STR2EUC> C<STR2SJIS>
+
+See L<Dialect::Japanese::String>
+
 =head1 SEE ALSO
 
-L<Dialect::Japanese>
+L<Dialect::Japanese::Utils>,
+L<Dialect::Japanese::String>
 
 =head1 AUTHOR
 
diff --git a/fml/lib/FML/String.pm b/fml/lib/Dialect/Japanese/String.pm
index 36dca505..4e748e4b 100644
--- a/fml/lib/FML/String.pm
+++ b/fml/lib/Dialect/Japanese/String.pm
@@ -8,18 +8,18 @@
 # $FML$
 #
 
-package FML::String;
+package Dialect::Japanese::String;
 use strict;
 use Carp;
 use vars qw(@ISA @EXPORT @EXPORT_OK);
 
 =head1 NAME
 
-FML::String -- utilities to manipulate strings
+Dialect::Japanese::String -- utilities to manipulate strings
 
 =head1 SYNOPSIS
 
-    use FML::String qw(STR2JIS);
+    use Dialect::Japanese::String qw(STR2JIS);
     $euc_str = STR2JIS($str);
 
 =head1 METHOD
@@ -83,7 +83,7 @@ redistribute it and/or modify it under the same terms as Perl itself.
 
 =head1 HISTORY
 
-FML::String appeared in fml5 mailing list driver package.
+Dialect::Japanese::String appeared in fml5 mailing list driver package.
 See C<http://www.fml.org/> for more details.
 
 =cut
diff --git a/fml/lib/Dialect/Japanese/index.ja.html b/fml/lib/Dialect/Japanese/index.ja.html
index 8ec9e260..cb59d549 100644
--- a/fml/lib/Dialect/Japanese/index.ja.html
+++ b/fml/lib/Dialect/Japanese/index.ja.html
@@ -14,6 +14,12 @@ Dialect/Japanese::* classes
 <TABLE BRODER=4>
 <TR>
 <TD>
+ Dialect::Japanese::String <TD>
+<A HREF="String.pm">[source]</A>
+<TD>
+<A HREF="@@doc/String.txt">[doc]</A>
+<TR>
+<TD>
  Dialect::Japanese::Subject <TD>
 <A HREF="Subject.pm">[source]</A>
 <TD>
diff --git a/fml/lib/FML/Date.pm b/fml/lib/FML/Date.pm
index 1e871aba..eeea51da 100644
--- a/fml/lib/FML/Date.pm
+++ b/fml/lib/FML/Date.pm
@@ -35,9 +35,10 @@ The style you use follows:
     precise_current_time        20010107210619
 
 
-=head1 METHOD
+=head1 METHODS
 
 You can also method like $date->$style() style.
+specify the C<style> name described above as a method.
 
 =item    log_file_style()
 
@@ -51,10 +52,11 @@ You can also method like $date->$style() style.
 
 =item    stardate()
 
-return STAR TREK stardate.
+return STAR TREK stardate :-)
 
 =cut
 
+
 require Exporter;
 use vars qw($TimeZone);
 @ISA = qw(Exporter);
@@ -200,4 +202,23 @@ sub stardate
 }
 
 
+=head1 AUTHOR
+
+Ken'ichi Fukamachi
+
+=head1 COPYRIGHT
+
+Copyright (C) 2001 Ken'ichi Fukamachi
+
+All rights reserved. This program is free software; you can
+redistribute it and/or modify it under the same terms as Perl itself. 
+
+=head1 HISTORY
+
+FML::Date appeared in fml5 mailing list driver package.
+See C<http://www.fml.org/> for more details.
+
+=cut
+
+
 1;
diff --git a/fml/lib/FML/index.ja.html b/fml/lib/FML/index.ja.html
index ba4f0915..e2bd0737 100644
--- a/fml/lib/FML/index.ja.html
+++ b/fml/lib/FML/index.ja.html
@@ -98,12 +98,6 @@ FML::* classes
  <A HREF=Process/index.ja.html>FML::Process::* class</A>
 <TR>
 <TD>
- FML::String <TD>
-<A HREF="String.pm">[source]</A>
-<TD>
-<A HREF="@@doc/String.txt">[doc]</A>
-<TR>
-<TD>
  <A HREF=Ticket/index.ja.html>FML::Ticket::* class</A>
 </TABLE>
 </BODY>
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.
diff --git a/fml/lib/MailingList/Delivery.pm b/fml/lib/MailingList/Delivery.pm
index 9ffed9f4..282f0185 100644
--- a/fml/lib/MailingList/Delivery.pm
+++ b/fml/lib/MailingList/Delivery.pm
@@ -73,15 +73,11 @@ C<LMTP> classes.
 
 =item C<new($args)>
 
-constructor. The request is forwarded up to SUPER class.
+constructor. The request is forwarded to SUPER class.
 
 =cut
 
 
-require Exporter;
-@ISA = qw(Exporter);
-
-
 sub new
 {
     my ($self, $args) = @_;
diff --git a/fml/lib/MailingList/SMTP.pm b/fml/lib/MailingList/SMTP.pm
index b525d96a..94454c87 100644
--- a/fml/lib/MailingList/SMTP.pm
+++ b/fml/lib/MailingList/SMTP.pm
@@ -28,7 +28,7 @@ END   {}
 
 =head1 NAME
 
-MailingList::SMTP.pm - interface for SMTP service
+MailingList::SMTP - interface for SMTP service
 
 =head1 SYNOPSIS
 
diff --git a/regress/base/string.pl b/regress/base/string.pl
index 733ac426..8895e12f 100755
--- a/regress/base/string.pl
+++ b/regress/base/string.pl
@@ -1,7 +1,20 @@
-use lib qw(./lib/fml5 ./lib/CPAN ./lib/3RDPARTY ./lib);
-use FML::String qw(STR2EUC);
+#!/usr/local/bin/perl
+#-*- perl -*-
+#
+#  Copyright (C) 2001 Ken'ichi Fukamachi
+#   All rights reserved. This program is free software; you can
+#   redistribute it and/or modify it under the same terms as Perl itself. 
+#
+# $Id$
+# $FML$
+#
+
+use lib qw(./lib/ ../../cpan/lib);
+use Dialect::ISO2022JP qw(STR2EUC);
 
 for (@ARGV) {
     my $x = &STR2EUC($_);
     print "<$_> -> <$x>\n";
 }
+
+exit 0;
diff --git a/regress/simulation/todo/doc b/regress/simulation/todo/doc
index c574fc30..ef4db9c6 100644
--- a/regress/simulation/todo/doc
+++ b/regress/simulation/todo/doc
@@ -1,7 +1,6 @@
 FML/Article.pm
 FML/Config.pm
 FML/Credential.pm
-FML/Date.pm
 FML/Header.pm
 FML/Parse.pm
 FML/Ticket/Model/toymodel.pm
@@ -16,14 +15,11 @@ FML/Process/Command.pm
 FML/Process/Switch.pm
 FML/Header/Subject.pm
 
-IO/Adapter/File.pm
-IO/Adapter/LDAP.pm
 IO/Adapter/NIS.pm
 IO/Adapter/RDBMS.pm
 IO/Adapter/UnixGroup.pm
 IO/Adapter/Array.pm
 IO/MapAdapter.pm
-IO/File/Atomic.pm
 
 Dialect/Japanese/Subject.pm
 Dialect/Japanese/Utils.pm
@@ -31,6 +27,4 @@ Dialect/Japanese/Utils.pm
 MailingList/Net/INET4.pm
 MailingList/Net/INET6.pm
 MailingList/Messages.pm
-MailingList/SMTP.pm
-MailingList/Delivery.pm
 MailingList/Utils.pm