- Enhanced axis class level documentation

4 files changed, 211 insertions, 18 deletions

diff --git a/src/axis/date.php b/src/axis/date.php
index e334154..b8d6018 100644
--- a/src/axis/date.php
+++ b/src/axis/date.php
@@ -8,14 +8,62 @@
  * @license http://ez.no/licenses/new_bsd New BSD License
  */
 /**
- * Class to represent date axis. Date axis will try to find a "nice" interval
- * based on the values on the x axis. If non numeric values are given, 
- * ezcGraphChartElementDateAxis will convert them to timestamps using PHPs 
- * strtotime function.
+ * Class to represent date axis.
+ *
+ * Axis elements represent the axis in a bar, line or radar chart. They are
+ * chart elements (ezcGraphChartElement) extending from
+ * ezcGraphChartElementAxis, where additional formatting options can be found.
+ * You should generally use the axis, which matches your input data best, so
+ * that the automatic chart layouting works best. Aavailable axis types are:
+ *
+ * - ezcGraphChartElementDateAxis
+ * - ezcGraphChartElementLabeledAxis
+ * - ezcGraphChartElementLogarithmicalAxis
+ * - ezcGraphChartElementNumericAxis
+ *
+ * Date axis will try to find a "nice" interval based on the values on the x
+ * axis. If non numeric values are given, ezcGraphChartElementDateAxis will
+ * convert them to timestamps using PHPs strtotime function.
  *
  * It is always possible to set start date, end date and the interval manually
  * by yourself.
  *
+ * The $dateFormat option provides an additional way of formatting the labels
+ * used on the axis. The options from the parent class $formatString and
+ * $labelCallback do still apply.
+ *
+ * You may use a date axis like in the following example:
+ *
+ * <code>
+ *  $graph = new ezcGraphLineChart();
+ *  $graph->options->fillLines = 210;
+ *  $graph->title = 'Concurrent requests';
+ *  $graph->legend = false;
+ *  
+ *  $graph->xAxis = new ezcGraphChartElementDateAxis();
+ *  
+ *  // Add data
+ *  $graph->data['Machine 1'] = new ezcGraphArrayDataSet( array(
+ *      '8:00' => 3241,
+ *      '8:13' => 934,
+ *      '8:24' => 1201,
+ *      '8:27' => 1752,
+ *      '8:51' => 123,
+ *  ) );
+ *  $graph->data['Machine 2'] = new ezcGraphArrayDataSet( array(
+ *      '8:05' => 623,
+ *      '8:12' => 2103,
+ *      '8:33' => 543,
+ *      '8:43' => 2034,
+ *      '8:59' => 3410,
+ *  ) );
+ *  
+ *  $graph->data['Machine 1']->symbol = ezcGraph::BULLET;
+ *  $graph->data['Machine 2']->symbol = ezcGraph::BULLET;
+ *  
+ *  $graph->render( 400, 150, 'tutorial_axis_datetime.svg' );
+ * </code>
+ *
  * @property float $startDate
  *           Starting date used to display on axis.
  * @property float $endDate
diff --git a/src/axis/labeled.php b/src/axis/labeled.php
index d8fda5b..4992270 100644
--- a/src/axis/labeled.php
+++ b/src/axis/labeled.php
@@ -8,8 +8,57 @@
  * @license http://ez.no/licenses/new_bsd New BSD License
  */
 /**
- * Class to represent a labeled axis. Values on the x axis are considered as 
- * strings and used in the given order.
+ * Class to represent a labeled axis.
+ *
+ * Axis elements represent the axis in a bar, line or radar chart. They are
+ * chart elements (ezcGraphChartElement) extending from
+ * ezcGraphChartElementAxis, where additional formatting options can be found.
+ * You should generally use the axis, which matches your input data best, so
+ * that the automatic chart layouting works best. Aavailable axis types are:
+ *
+ * - ezcGraphChartElementDateAxis
+ * - ezcGraphChartElementLabeledAxis
+ * - ezcGraphChartElementLogarithmicalAxis
+ * - ezcGraphChartElementNumericAxis
+ *
+ * The labeled axis will accept any values and converts them to strings. The
+ * labeled axis does not know about any special meanings of values and
+ * maintains the order of the given labels with equidistant spaces between all
+ * values. If your data has a special meaning, like a set of numbers or dates,
+ * use one of the other more appropriate axis.
+ *
+ * Because it is not always possible to fit all labels in a chart you may
+ * define the count of labels drawn using the $labelCount option. For all other
+ * labels only a small step will be rendered.
+ *
+ * The labeled axis may be used like:
+ *
+ * <code>
+ *  $graph = new ezcGraphLineChart();
+ *  $graph->options->fillLines = 210;
+ *  $graph->options->font->maxFontSize = 10;
+ *  $graph->title = 'Error level colors';
+ *  $graph->legend = false;
+ *  
+ *  $graph->yAxis = new ezcGraphChartElementLabeledAxis();
+ *  $graph->yAxis->axisLabelRenderer->showZeroValue = true;
+ *  
+ *  $graph->yAxis->label = 'Color';
+ *  $graph->xAxis->label = 'Error level';
+ *  
+ *  // Add data
+ *  $graph->data['colors'] = new ezcGraphArrayDataSet(
+ *      array(
+ *          'info' => 'blue',
+ *          'notice' => 'green',
+ *          'warning' => 'orange',
+ *          'error' => 'red',
+ *          'fatal' => 'red',
+ *      )
+ *  );
+ *  
+ *  $graph->render( 400, 150, 'tutorial_axis_labeled.svg' );
+ * </code>
  *
  * @property float $labelCount
  *           Define count of displayed labels on the axis
diff --git a/src/axis/logarithmic.php b/src/axis/logarithmic.php
index 8914aee..0edf7ee 100644
--- a/src/axis/logarithmic.php
+++ b/src/axis/logarithmic.php
@@ -8,17 +8,55 @@
  * @license http://ez.no/licenses/new_bsd New BSD License
  */
 /**
- * Class to represent a numeric axis. The axis tries to calculate "nice" start
- * and end values for the axis scale. The used interval is considered as nice, 
- * if it is equal to [1,2,5] * 10^x with x in [.., -1, 0, 1, ..].
+ * Class to represent a logarithmic axis.
  *
- * The start and end value are the next bigger / smaller multiple of the 
- * intervall compared to the maximum / minimum axis value.
+ * Axis elements represent the axis in a bar, line or radar chart. They are
+ * chart elements (ezcGraphChartElement) extending from
+ * ezcGraphChartElementAxis, where additional formatting options can be found.
+ * You should generally use the axis, which matches your input data best, so
+ * that the automatic chart layouting works best. Aavailable axis types are:
+ *
+ * - ezcGraphChartElementDateAxis
+ * - ezcGraphChartElementLabeledAxis
+ * - ezcGraphChartElementLogarithmicalAxis
+ * - ezcGraphChartElementNumericAxis
+ *
+ * Logarithmic axis are normally used to display very large or small values.
+ * Logarithmic axis can not be used for value spans including zero, so you
+ * should either pass only positive or only negative values to the chart.
+ *
+ * By default the axis uses a base of 10 for scaling, you may assign any other
+ * base to the $base property of the chart. With a base of 10 the steps on the
+ * axis may, for example, be at: 1, 10, 100, 1000, 10000, ...
+ *
+ * The logarithmic axis may be used like:
+ *
+ * <code>
+ *  $graph = new ezcGraphLineChart();
+ *  $graph->title = 'The power of x';
+ *  $graph->legend->position = ezcGraph::BOTTOM;
+ *  
+ *  $graph->xAxis = new ezcGraphChartElementNumericAxis();
+ *  $graph->yAxis = new ezcGraphChartElementLogarithmicalAxis();
+ *  
+ *  $graph->data['x^2'] = new ezcGraphNumericDataSet( 
+ *      -10, 10,
+ *      create_function( '$x', 'return pow( $x, 2 ) + 1;' )
+ *  );
+ *  
+ *  $graph->data['x^4'] = new ezcGraphNumericDataSet( 
+ *      -10, 10,
+ *      create_function( '$x', 'return pow( $x, 4 ) + 1;' )
+ *  );
+ *  
+ *  $graph->data['x^6'] = new ezcGraphNumericDataSet( 
+ *      -10, 10,
+ *      create_function( '$x', 'return pow( $x, 6 ) + 1;' )
+ *  );
+ *  
+ *  $graph->render( 400, 250, 'tutorial_axis_logarithmic.svg' );
+ * </code>
  *
- * @property float $min
- *           Minimum value of displayed scale on axis.
- * @property float $max
- *           Maximum value of displayed scale on axis.
  * @property float $base
  *           Base for logarithmical scaling.
  * @property string $logarithmicalFormatString
diff --git a/src/axis/numeric.php b/src/axis/numeric.php
index 2a443c1..ab709db 100644
--- a/src/axis/numeric.php
+++ b/src/axis/numeric.php
@@ -8,17 +8,75 @@
  * @license http://ez.no/licenses/new_bsd New BSD License
  */
 /**
- * Class to represent a numeric axis. The axis tries to calculate "nice" start
- * and end values for the axis scale. The used interval is considered as nice, 
- * if it is equal to [1,2,5] * 10^x with x in [.., -1, 0, 1, ..].
+ * Class to represent a numeric axis.
+ *
+ * Axis elements represent the axis in a bar, line or radar chart. They are
+ * chart elements (ezcGraphChartElement) extending from
+ * ezcGraphChartElementAxis, where additional formatting options can be found.
+ * You should generally use the axis, which matches your input data best, so
+ * that the automatic chart layouting works best. Aavailable axis types are:
+ *
+ * - ezcGraphChartElementDateAxis
+ * - ezcGraphChartElementLabeledAxis
+ * - ezcGraphChartElementLogarithmicalAxis
+ * - ezcGraphChartElementNumericAxis
+ *
+ * The axis tries to calculate "nice" start and end values for the axis scale.
+ * The used interval is considered as nice, if it is equal to [1,2,5] * 10^x
+ * with x in [.., -1, 0, 1, ..].
  *
  * The start and end value are the next bigger / smaller multiple of the 
  * intervall compared to the maximum / minimum axis value.
  *
+ * You may specify custom step sizes using the properties $majorStep and
+ * $minorStep. The minimum and maximum values for the axis labels can be
+ * defined using the $min and $max properties. You should be able to set any
+ * subset of these values, and all values not explicitely set will be
+ * calculated automatically.
+ *
+ * This axis should be used for all numeric values except dates. If your data
+ * does span very big number intervals you might want to consider using the
+ * logrithmic axis instead.
+ *
+ * The numeric axis may be used like:
+ *
+ * <code>
+ *  $graph = new ezcGraphLineChart();
+ *  $graph->title = 'Some random data';
+ *  $graph->legend = false;
+ *  
+ *  $graph->xAxis = new ezcGraphChartElementNumericAxis();
+ *  // The y axis is numeric by default.
+ *  
+ *  $graph->xAxis->min = -15;
+ *  $graph->xAxis->max = 15;
+ *  $graph->xAxis->majorStep = 5;
+ *  
+ *  $data = array(
+ *      array(),
+ *      array()
+ *  );
+ *  for ( $i = -10; $i <= 10; $i++ )
+ *  {
+ *      $data[0][$i] = mt_rand( -23, 59 );
+ *      $data[1][$i] = mt_rand( -23, 59 );
+ *  }
+ *  
+ *  // Add data
+ *  $graph->data['random blue'] = new ezcGraphArrayDataSet( $data[0] );
+ *  $graph->data['random green'] = new ezcGraphArrayDataSet( $data[1] );
+ *  
+ *  $graph->render( 400, 150, 'tutorial_axis_numeric.svg' );
+ * </code>
+ *
  * @property float $min
  *           Minimum value of displayed scale on axis.
  * @property float $max
  *           Maximum value of displayed scale on axis.
+ * @property mixed $majorStep
+ *           Labeled major steps displayed on the axis.
+ * @property mixed $minorStep
+ *           Non labeled minor steps on the axis.
  * @property-read float $minValue
  *                Minimum Value to display on this axis.
  * @property-read float $maxValue