From 2df211737b5ddaa87c41036b9b2b670f38f9640f Mon Sep 17 00:00:00 2001
From: hjp <hjp>
Date: Mon, 14 Feb 2005 16:07:20 +0000
Subject: [PATCH] Added documentation (finally!). Fixed log_x and log_y methods
 to allow turning off log scaling (this isn't really needed because linear
 scaling is the default, but it was still a bug).

---
 TimeSeries.pm | 120 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 117 insertions(+), 3 deletions(-)

diff --git a/TimeSeries.pm b/TimeSeries.pm
index f236e3e..d229d40 100644
--- a/TimeSeries.pm
+++ b/TimeSeries.pm
@@ -1,12 +1,62 @@
 package TimeSeries;
 
+=head1 NAME
+
+TimeSeries - create plots of time series 
+
+=head1 SYNOPSIS
+
+my $ts = TimeSeries->new(style=>lines, output_format => ps);
+$ts->legend('Bugs reported', 'Bugs fixed');
+$ts->add(1108394622, 42, 23);
+$ts->add_timestring('2005-02-01', 33, 39);
+print PSFILE $ts->plot;
+
+=head1 DESCRIPTION
+
+This module uses Gnuplot to create plots of multiple timeseries.
+Actually it should do all kinds of useful operations on timeseries, 
+but right now only adding data and plotting the whole thing is
+implemented.
+
+=cut
+
 use File::Temp qw(tempfile);
 use Time::Local;
 use Data::Dumper;
 use HTTP::Date qw(parse_date);
 use Time::Local qw(timegm_nocheck);
 
-$VERSION = do { my @r=(q$Revision: 1.7 $=~/\d+/g);sprintf "%d."."%02d"x$#r,@r};
+$VERSION = do { my @r=(q$Revision: 1.8 $=~/\d+/g);sprintf "%d."."%02d"x$#r,@r};
+
+=head2 new(%opts)
+
+Creates a new timeseries object. Possible options are:
+
+=over
+
+=item style
+
+The style for the data. This must be one of the styles supported by
+Gnuplot for two-column 2D data, e.g, "bargraph", "boxes", "dots",
+"fsteps", "impulses", "lines", "linespoints", "points", "steps".
+
+The default is "lines".
+
+=item output_format
+
+The output file format. Possible values are "ps" (Postscript), "png",
+"gif" and "jpeg". In the last three cases, a postscript file is created
+first, then printed to a 150dpi ppm file, rotated, scaled down (with
+antialiasing) to 75 dpi and finally converted to the requested file
+format. This usually results in prettier output than letting gnuplot
+create the file directly.
+
+The default is "png".
+
+=back
+
+=cut
 
 sub new {
     my ($class, %opts) = @_;
@@ -20,6 +70,12 @@ sub new {
     return $self;
 }
 
+=item add($timestamp, @data)
+
+Adds data (one entry for each timeseries) for time $timestamp.
+$timestamp is in seconds since the epoch.
+
+=cut
 
 sub add {
     my ($self, $timestamp, @data) = @_;
@@ -28,6 +84,14 @@ sub add {
     #print Dumper($self);
 }
 
+=item add_timestring($timestring, @data)
+
+Adds data (one entry for each timeseries) for time $timestring.
+$timestring can be any string parseable by the parse_date function of
+the HTTP::Date module.
+
+=cut
+
 sub add_timestring {
     my ($self, $timestring, @data) = @_;
 
@@ -50,6 +114,12 @@ sub add_timestring {
 }
 
 
+=head2 legend(@legend)
+
+Set the legend for the timeseries (One string per series).
+
+=cut
+
 sub legend {
     my ($self, @legend) = @_;
     my $oldlegend = $self->{legend};
@@ -57,6 +127,15 @@ sub legend {
     return $oldlegend ? @$oldlegend : ();
 }
 
+=head2 style([$style])
+
+Sets a new style if $style is given. In any case the old style is
+returned.
+
+See new() for details about styles.
+
+=cut
+
 sub style {
     my ($self, $style) = @_;
     my $oldstyle = $self->{style};
@@ -64,20 +143,47 @@ sub style {
     return $oldstyle;
 }
 
+=head2 log_x([$log])
+
+if $log is non-zero, the x axis is scaled logarithmically,
+if it is 0, the x axis is scaled linearly.
+
+The return value is the old value of this setting.
+
+=cut
+
 sub log_x {
     my ($self, $log_x) = @_;
     my $oldlog_x = $self->{log_x};
-    $self->{log_x} = $log_x if ($log_x);
+    $self->{log_x} = $log_x if (defined($log_x));
     return $oldlog_x;
 }
 
+=head2 log_y([$log])
+
+if $log is non-zero, the y axis is scaled logarithmically,
+if it is 0, the y axis is scaled linearly.
+
+The return value is the old value of this setting.
+
+=cut
+
 sub log_y {
     my ($self, $log_y) = @_;
     my $oldlog_y = $self->{log_y};
-    $self->{log_y} = $log_y if ($log_y);
+    $self->{log_y} = $log_y if (defined($log_y));
     return $oldlog_y;
 }
 
+=head2 output_format([$output_format])
+
+Sets a new output format if $output_format is given. In any case the old
+output format is returned.
+
+See new() for details about output formats.
+
+=cut
+
 sub output_format {
     my ($self, $output_format) = @_;
     my $oldoutput_format = $self->{output_format};
@@ -100,6 +206,9 @@ seconds) later, the time is 2003-03-30 05:00:00 CEST. To get back to a
 C<dstcorr(1048993200, 14400)> returns 1048989600, which is 2003-03-30
 04:00:00 CEST.
 
+This is an internal function which normally doesn't need to be called by
+the user.
+
 =cut
 
 sub dstcorr {
@@ -121,6 +230,11 @@ sub dstcorr {
     return $time;
 }
 
+=head2 plot
+
+Returns a string with the plot of the timeseries.
+
+=cut
 
 sub plot {
     my ($self) = @_;