fu: Close-up of Fu, bringing a scoop of water to her mouth (Default)
fu ([personal profile] fu) wrote in [site community profile] changelog2011-09-06 11:47 am

[dw-free] stats: make graphs link to larger versions

[commit: http://hg.dwscoalition.org/dw-free/rev/751c3341fa10]

http://bugs.dwscoalition.org/show_bug.cgi?id=3157

PODify in-code documentation, so that we can generate user-friendly
documentation. No functional change.

Patch by [personal profile] pauamma.

Files modified:
  • cgi-bin/DW/Graphs.pm
--------------------------------------------------------------------------------
diff -r d3ad79fc1574 -r 751c3341fa10 cgi-bin/DW/Graphs.pm
--- a/cgi-bin/DW/Graphs.pm	Tue Sep 06 18:40:01 2011 +0800
+++ b/cgi-bin/DW/Graphs.pm	Tue Sep 06 19:47:14 2011 +0800
@@ -5,7 +5,7 @@
 # Authors:
 #      Anarres <anarres@dreamwidth.org>
 #
-# Copyright (c) 2010 by Dreamwidth Studios, LLC.
+# Copyright (c) 2010-2011 by Dreamwidth Studios, LLC.
 #
 # This program is free software; you may redistribute it and/or modify it under
 # the same terms as Perl itself. For a copy of the license, please reference
@@ -26,6 +26,31 @@
 use GD::Graph::colour;
 use YAML ();
 
+=head1 NAME
+
+DW::Graphs - creates graphs for the statistics system
+
+=head1 SYNOPSIS
+
+  use DW::Graphs;
+  my $pie = DW::Graphs::pie( { Ponies => 5, Rainbows => 1, Unicorns => 3 } );
+  # Display $pie->png using your favorite library
+  my $bar = DW::Graphs::bar( [ 5, 1, 3 ], [ qw( Ponies Rainbows Unicorns ) ],
+                                  'Critter', 'Count' );
+  # Display $bar->png using your favorite library
+  my $bars = DW::Graphs::bar2( [ [ qw( Ponies Rainbows Unicorns ) ],
+                                 [ 5, 1, 3 ], [ 2, 0, 1 ] ],
+                               'Critter', 'Count',
+                               [ qw( Plain Sparkly ) ] );
+  # Display $bars->png using your favorite library
+  my $lines = DW::Graphs::lines( [ [ qw( Ponies Rainbows Unicorns ) ],
+                                   [ 5, 1, 3 ], [ 2, 0, 1 ] ],
+                                 'Critter', 'Count',
+                                 [ qw( Plain Sparkly ) ] );
+  # Display $lines->png using your favorite library
+
+=cut
+
 # Define colours - the arrays can be over-ridden by config file
 my $background = '#f7f7f7';
 my $nearly_white = '#f8f8f8';
@@ -43,9 +68,18 @@
     axis_size => 10,
     legend_size => 12,
 );
-# Generates a pie chart. The argument is a hashref of labels and values.
-# Returns graph object $gd which can be printed with the command: print $gd->png;
-# See ~/dw/bin/dev/graphs_usage.pl for more detailed usage information.
+
+=head1 API
+
+=head2 C<< DW::Graphs::pie( $data [, $config_filename ] ) >>
+
+Creates pie chart from $data (slice_label => slice_value hashref), using
+optional $config_filename to override defaults. Returns a GD::Graph::pie.
+
+See ~/dw/bin/dev/graphs_usage.pl for more detailed usage information.
+
+=cut
+
 sub pie {
     my ( $pie_ref, $config_filename ) = @_;
 
@@ -110,10 +144,16 @@
     return $gd;
 }
 
-# Generates a bar chart. Arguments: a ref to an array of values, a ref to an
-# array of labels, title, x-axis label, y-axis label. # Returns graph object
-# $gd which can be printed with the command: print $gd->png; see
-# graphs_usage.pl for more detailed usage information.
+=head2 C<< DW::Graphs::bar( $values_ref, $labels_ref, $xlabel, $ylabel [, $config_filename ] ) >>
+
+Creates bar chart from $values_ref (value arrayref), $labels_ref (label
+arrayref), $xlabel, $ylabel, using optional $config_filename to override
+defaults. Returns a GD::Graph::bars.
+
+See ~/dw/bin/dev/graphs_usage.pl for more detailed usage information.
+
+=cut
+
 sub bar {
     my ( $values_ref, $labels_ref, $xlabel, $ylabel, $config_filename ) = @_;
 
@@ -188,11 +228,17 @@
     return $gd;
 }
 
-# Generates a bar chart with two or more sets of data represented by each bar.
-# Arguments: a reference containing labels and datasets, x-axis label,
-# y-axis label, ref to array of names for datasets. Returns graph object
-# $gd which can be printed with the command: print $gd->png; see
-# ~/dw/bin/dev/graphs_usage.pl for more detailed usage information.
+=head2 C<< DW::Graphs::bar2( $values_ref, $labels_ref, $xlabel, $ylabel [, $config_filename ] ) >>
+
+Creates bar chart with two or more sets of data from $ref ([ [ @value_labels ],
+[ @dataset1 ], [ @dataset2 ], ... ]), $xlabel, $ylabel, $names_ref (label
+arrayref, must have 1 element per dataset), using optional $config_filename to
+override defaults. Returns a GD::Graph::bars.
+
+See ~/dw/bin/dev/graphs_usage.pl for more detailed usage information.
+
+=cut
+
 sub bar2 {
     my ( $ref, $xlabel, $ylabel, $names_ref, $config_filename ) = @_;
 
@@ -273,10 +319,17 @@
     return $gd;
 }
 
-# Generates a line graph. Arguments: a reference containing labels and datasets,
-# x-axis label, y-axis label, ref to array of names for datasets. Returns
-# graph object $gd which can be printed with the command: print $gd->png; see
-# ~/dw/bin/dev/graphs_usage.pl for more detailed usage information.
+=head2 C<< DW::Graphs::bar2( $values_ref, $labels_ref, $xlabel, $ylabel [, $config_filename ] ) >>
+
+Creates line graph with two or more sets of data from $ref ([ [ @value_labels ],
+[ @dataset1 ], [ @dataset2 ], ... ]), $xlabel, $ylabel, $names_ref (label
+arrayref, must have 1 element per dataset), using optional $config_filename to
+override defaults. Returns a GD::Graph::bars.
+
+See ~/dw/bin/dev/graphs_usage.pl for more detailed usage information.
+
+=cut
+
 sub lines {
     my ( $data_ref, $xlabel, $ylabel, $data_names, $config_filename ) = @_;
 
@@ -351,3 +404,13 @@
 }
 
 1;
+
+=head1 AUTHORS AND COPYRIGHT
+
+Authors: Anarres <anarres@dreamwidth.org>
+
+Copyright (c) 2010-2011 by Dreamwidth Studios, LLC.
+
+This program is free software; you may redistribute it and/or modify it under
+the same terms as Perl itself. For a copy of the license, please reference
+'perldoc perlartistic' or 'perldoc perlgpl'.
--------------------------------------------------------------------------------

Post a comment in response:

This account has disabled anonymous posting.
If you don't have an account you can create one now.
HTML doesn't work in the subject.
More info about formatting

If you are unable to use this captcha for any reason, please contact us by email at support@dreamwidth.org