clean up documents on File::

5 files changed, 84 insertions, 44 deletions

diff --git a/fml/lib/File/Errors.pm b/fml/lib/File/Errors.pm
index fcf07ffd..bf8779e7 100644
--- a/fml/lib/File/Errors.pm
+++ b/fml/lib/File/Errors.pm
@@ -43,7 +43,7 @@ When you use Something module,
 
 =head2 C<error_reason($message)>
 
-save $message
+save $message as an error message.
 
 =head2 C<error()>
 
diff --git a/fml/lib/File/RingBuffer.pm b/fml/lib/File/RingBuffer.pm
index 6c0f37ae..fda996b3 100644
--- a/fml/lib/File/RingBuffer.pm
+++ b/fml/lib/File/RingBuffer.pm
@@ -104,6 +104,11 @@ sub new
 }
 
 
+# Descriptions: determine the file name to write into
+#    Arguments: $self $args
+# Side Effects: increment $sequence_file_name
+#               set the file name at ${*$self}{ _file }
+# Return Value: none
 sub _take_file_name
 {
     my ($self, $args) = @_;
@@ -144,6 +149,10 @@ sub open
 }
 
 
+# Descriptions: forward close() to SUPER class
+#    Arguments: $self
+# Side Effects: none
+# Return Value: value returned by SUPER::close()
 sub close
 {
     my ($self) = @_;
diff --git a/fml/lib/File/Rotate.pm b/fml/lib/File/Rotate.pm
index 6d5ef440..4c146414 100644
--- a/fml/lib/File/Rotate.pm
+++ b/fml/lib/File/Rotate.pm
@@ -65,6 +65,10 @@ sub new
 }
 
 
+# Descriptions: determine the time to rotate comes
+#    Arguments: $self
+# Side Effects: none
+# Return Value: 1 (time comes!) or 0
 sub is_time_to_rotate
 {
     my ($self) = @_;
@@ -78,6 +82,12 @@ sub is_time_to_rotate
 }
 
 
+
+# Descriptions: rotate filenames
+#    Arguments: $self
+# Side Effects: filename rotations
+#               unlink the oldest file
+# Return Value: none
 sub rotate
 {
     my ($self) = @_;
@@ -98,6 +108,10 @@ sub rotate
 }
 
 
+# Descriptions: extract parameters in $self
+#    Arguments: $self
+# Side Effects: none
+# Return Value: a set of (file, max_size, num_backlog)
 sub _get_param
 {
     my ($self) = @_;
@@ -122,6 +136,7 @@ sub error
 
 Ken'ichi Fukamachi
 
+
 =head1 COPYRIGHT
 
 Copyright (C) 2001 Ken'ichi Fukamachi
@@ -136,4 +151,5 @@ See C<http://www.fml.org/> for more details.
 
 =cut
 
+
 1;
diff --git a/fml/lib/File/SimpleLock.pm b/fml/lib/File/SimpleLock.pm
index 1afa0b3c..e15fdb24 100644
--- a/fml/lib/File/SimpleLock.pm
+++ b/fml/lib/File/SimpleLock.pm
@@ -11,6 +11,9 @@ package File::SimpleLock;
 use vars qw(%LockedFileHandle %FileIsLocked @ISA $Error);
 use strict;
 use Carp;
+use File::Errors;
+
+@ISA = qw(File::Errors);
 
 =head1 NAME
 
@@ -18,7 +21,7 @@ File::SimpleLock - simple lock by flock(2)
 
 =head1 SYNOPSIS
 
-    require File::SimpleLock;
+    use File::SimpleLock;
     my $lockobj = new File::SimpleLock;
     $lockobj->lock( { file => $lock_file } ) || croak "fail to lock";
 
@@ -28,17 +31,20 @@ File::SimpleLock - simple lock by flock(2)
 
 =head1 DESCRIPTION
 
-File::SimpleLock.pm contains several interfaces for several files,
+File::SimpleLock module contains several interfaces for several files,
 for example, Lockfiles, sysLock() (not yet implemented).
 
-=item Lock( $message )
+=head1 METHODS
 
-The argument is the message to Lock.
+=head2 C<lock($args)>
 
-=cut
+flock(2) for $args->{ file };
 
-require Exporter;
-@ISA = qw(Exporter);
+=head2 C<unlock($args)> 
+
+unlock flock(2) for $args->{ file };
+
+=cut
 
 
 # constants
@@ -58,26 +64,12 @@ sub new
 }
 
 
-sub _error_reason
-{
-    my $msg = @_;
-    $Error = $msg;
-}
-
-
-sub error
-{
-    my ($self) = @_;
-    $Error;
-}
-
-
 sub lock
 {
     my ($self, $args) = @_;
 
     my $file = $args->{ file };
-    _simple_flock($file);
+    $self->_simple_flock($file);
 }
 
 
@@ -86,14 +78,14 @@ sub unlock
     my ($self, $args) = @_;
 
     my $file = $args->{ file };
-    _simple_funlock($file);
+    $self->_simple_funlock($file);
 }
 
 
 
 sub _simple_flock
 {
-    my ($file) = @_;
+    my ($self, $file) = @_;
 
     use FileHandle;
     my $fh = new FileHandle $file;
@@ -105,7 +97,7 @@ sub _simple_flock
 	eval q{
 	    $r = flock($fh, &LOCK_EX);
 	};
-	_error_reason($@) if $@;
+	$self->error_reason($@) if $@;
 
 	if ($r) {
 	    $FileIsLocked{ $file } = 1;
@@ -113,7 +105,7 @@ sub _simple_flock
 	}
     }
     else {
-	_error_reason("cannot open $file");
+	$self->error_reason("cannot open $file");
     }
 
     return 0;
@@ -122,7 +114,7 @@ sub _simple_flock
 
 sub _simple_funlock
 {
-    my ($file) = @_;
+    my ($self, $file) = @_;
 
     return 0 unless $FileIsLocked{ $file };
     return 0 unless $LockedFileHandle{ $file };
@@ -133,7 +125,7 @@ sub _simple_funlock
     eval q{
 	$r = flock($fh, &LOCK_UN);
     };
-    _error_reason($@) if $@;
+    $self->error_reason($@) if $@;
 
     if ($r) {
 	delete $FileIsLocked{ $file };
@@ -147,7 +139,8 @@ sub _simple_funlock
 
 =head1 SEE ALSO
 
-L<FileHandle>
+L<FileHandle>,
+L<File::Errors>,
 
 =head1 AUTHOR
 
@@ -155,7 +148,7 @@ Ken'ichi Fukamachi <F<fukachan@fml.org>>
 
 =head1 COPYRIGHT
 
-Copyright (C) 2000 Ken'ichi Fukamachi
+Copyright (C) 2000,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. 
diff --git a/fml/lib/File/Utils.pm b/fml/lib/File/Utils.pm
index e019d689..401768aa 100644
--- a/fml/lib/File/Utils.pm
+++ b/fml/lib/File/Utils.pm
@@ -29,26 +29,29 @@ File::Utils - error handling utilities
 
 =head1 DESCRIPTION
 
-=head1 AUTHOR
+this module provides utility functions to handle files, 
+for example, 
+C<mkdirhier>,
+C<touch>,
+C<search_program>
+and
+C<copy>.
 
-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
-
-File::Utils appeared in fml5 mailing list driver package.
-See C<http://www.fml.org/> for more details.
+=head1 METHODS
 
 =cut
 
+# Descriptions: return the error
+#    Arguments: none
+# Side Effects: none
+# Return Value: error message
 sub error       { return $ErrorString;}
 
+# Descriptions: remove the error message buffer
+#    Arguments: none
+# Side Effects: undef $ErrorString buffer
+# Return Value: none
 sub error_reset { undef $ErrorString;}
 
 
@@ -160,4 +163,23 @@ sub copy
 }
 
 
+=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
+
+File::Utils appeared in fml5 mailing list driver package.
+See C<http://www.fml.org/> for more details.
+
+=cut
+
+
 1;