- Enhanced chart element documentation

13 files changed, 293 insertions, 13 deletions

diff --git a/src/datasets/property/axis.php b/src/datasets/property/axis.php
index f813dd0..d5c0768 100644
--- a/src/datasets/property/axis.php
+++ b/src/datasets/property/axis.php
@@ -10,6 +10,12 @@
 /**
  * Class for axis properties of datasets
  *
+ * This class is used to store properties for datasets, which should be
+ * validated as objects extending the ezcGraphChartElementAxis class.
+ *
+ * For a basic usage example of those dataset properties take a look at the API
+ * documentation of the ezcGraphDataSetProperty class.
+ *
  * @version //autogentag//
  * @package Graph
  */
diff --git a/src/datasets/property/boolean.php b/src/datasets/property/boolean.php
index 6a046e9..24c92f6 100644
--- a/src/datasets/property/boolean.php
+++ b/src/datasets/property/boolean.php
@@ -8,7 +8,13 @@
  * @license http://ez.no/licenses/new_bsd New BSD License
  */
 /**
- * Class for integer properties of datasets
+ * Class for boolean properties of datasets
+ *
+ * This class is used to store properties for datasets, which should be
+ * validated as boolean values.
+ *
+ * For a basic usage example of those dataset properties take a look at the API
+ * documentation of the ezcGraphDataSetProperty class.
  *
  * @version //autogentag//
  * @package Graph
diff --git a/src/datasets/property/color.php b/src/datasets/property/color.php
index 07a74d2..f20d5cb 100644
--- a/src/datasets/property/color.php
+++ b/src/datasets/property/color.php
@@ -10,6 +10,12 @@
 /**
  * Class for color properties of datasets
  *
+ * This class is used to store properties for datasets, which should be
+ * validated as objects extending the ezcGraphColor class.
+ *
+ * For a basic usage example of those dataset properties take a look at the API
+ * documentation of the ezcGraphDataSetProperty class.
+ *
  * @version //autogentag//
  * @package Graph
  */
diff --git a/src/datasets/property/integer.php b/src/datasets/property/integer.php
index 3652efd..27c5ba5 100644
--- a/src/datasets/property/integer.php
+++ b/src/datasets/property/integer.php
@@ -10,6 +10,12 @@
 /**
  * Class for integer properties of datasets
  *
+ * This class is used to store properties for datasets, which should be
+ * validated as integer values.
+ *
+ * For a basic usage example of those dataset properties take a look at the API
+ * documentation of the ezcGraphDataSetProperty class.
+ *
  * @version //autogentag//
  * @package Graph
  */
diff --git a/src/datasets/property/string.php b/src/datasets/property/string.php
index 2f21656..423b6aa 100644
--- a/src/datasets/property/string.php
+++ b/src/datasets/property/string.php
@@ -10,6 +10,12 @@
 /**
  * Class for string properties of datasets
  *
+ * This class is used to store properties for datasets, which should be
+ * validated as string values.
+ *
+ * For a basic usage example of those dataset properties take a look at the API
+ * documentation of the ezcGraphDataSetProperty class.
+ *
  * @version //autogentag//
  * @package Graph
  */
diff --git a/src/element/axis.php b/src/element/axis.php
index 4eace35..d9b615e 100644
--- a/src/element/axis.php
+++ b/src/element/axis.php
@@ -8,7 +8,74 @@
  * @license http://ez.no/licenses/new_bsd New BSD License
  */
 /**
- * Basic axis class
+ * Class to represent an axis as a chart element
+ *
+ * Chart elements can be understood as widgets or layout container inside the
+ * chart. The actual transformation to images happens inside the renderers.
+ * They represent all elements inside the chart and contain mostly general
+ * formatting options, while the renderer itself might define additional
+ * formatting options for some chart elments. You can find more about the
+ * general formatting options for chart elements in the base class
+ * ezcGraphChartElement.
+ *
+ * The axis elements are special elements, as the border and background
+ * settings do not apply directly as axis axis are not put inside any boxes.
+ * The border value is reused for the color of the axis itself.
+ *
+ * Generally you should select the axis which matches your data best. By
+ * default a labeled x axis and a numeric y axis are used. If you are using
+ * date or time values on either axis, you should for example use a
+ * ezcGraphChartElementDateAxis. The currently available axis types are:
+ *
+ * - ezcGraphChartElementDateAxis
+ * - ezcGraphChartElementLabeledAxis
+ * - ezcGraphChartElementLogarithmicalAxis
+ * - ezcGraphChartElementNumericAxis
+ *
+ * Beside this there are several option to define the general layout of the
+ * axis labels. The $formatString option may be used to add additional text to
+ * each label on the axis, like a percent sign on the y axis:
+ *
+ * <code>
+ *  $chart->xAxis->formatString = '%s %%';
+ * </code>
+ *
+ * For more complex formatting operations for the label you may assign a custom
+ * formatter function to the property $labelCallback.
+ *
+ * The orientation of labels and their position relatively to the axis ticks is
+ * calcualted and rendered by the ezcGraphAxisLabelRenderer classes. You can
+ * choose between different axis label renderer, or create you own, and assign
+ * an instance of one to the property $axisLabelRenderer. Currently the
+ * available axis label renderers are:
+ * 
+ * - ezcGraphAxisBoxedLabelRenderer
+ *
+ *   Renders grid and labels like commonly used in bar charts, with the label
+ *   between two grid lines.
+ *  
+ * - ezcGraphAxisCenteredLabelRenderer
+ *
+ *   Centers the label right next to a tick. Commonly used for labeled axis.
+ *
+ * - ezcGraphAxisExactLabelRenderer
+ *
+ *   Put the label next to each tick. Commonly used for numeric axis.
+ *
+ * - ezcGraphAxisNoLabelRenderer
+ *
+ *   Renders no labels.
+ *
+ * - ezcGraphAxisRadarLabelRenderer
+ *
+ *   Special label renderer for radar charts.
+ *
+ * - ezcGraphAxisRotatedLabelRenderer
+ *
+ *   Accepts a rotation angle for the texts put at some axis, which might be
+ *   useful for longer textual labels on the axis.
+ *
+ * The label renderer used by default is different depending on the axis type.
  *
  * @property float $nullPosition
  *           The position of the null value.
diff --git a/src/element/background.php b/src/element/background.php
index 9238215..f0772c5 100644
--- a/src/element/background.php
+++ b/src/element/background.php
@@ -8,25 +8,44 @@
  * @license http://ez.no/licenses/new_bsd New BSD License
  */
 /**
- * Chart element representing the background. In addition to the standard 
- * background and border for chart elements it can draw an image on the chart 
- * background, and optionally repeat it. The position will be used for the 
- * repetition offset.
+ * Chart element representing the background.
+ *
+ * Chart elements can be understood as widgets or layout container inside the
+ * chart. The actual transformation to images happens inside the renderers.
+ * They represent all elements inside the chart and contain mostly general
+ * formatting options, while the renderer itself might define additional
+ * formatting options for some chart elments. You can find more about the
+ * general formatting options for chart elements in the base class
+ * ezcGraphChartElement.
+ *
+ * Additionally to common background and border for chart elements it can draw
+ * an image on the chart background, and optionally repeat it. The position
+ * will be used to define the start of the repetition.
+ *
+ * The repetition effects are modelled similar to the background settings in
+ * CSS. The example shows some common settings:
  *
  * <code>
+ *  $chart = new ezcGraphPieChart();
+ *  $chart->data['example'] = new ezcGraphArrayDataSet( array(
+ *      'Foo' => 23,
+ *      'Bar' => 42,
+ *  ) );
+ *
  *  $chart->background->image = 'background.png';
  *
- *  // Image will be repeated horizontal at the top of the background
+ *  // Image would be repeated horizontal at the top of the background
  *  $chart->background->repeat = ezcGraph::HORIZONTAL;
  *  $chart->background->postion = ezcGraph::TOP;
  *
- *  // Image will be placed once in the center
+ *  // Image would be placed once in the center
  *  $chart->background->repeat = ezcGraph::NO_REPEAT; // default;
  *  $chart->background->position = ezcGraph::CENTER | ezcGraph::MIDDLE;
  *
- *  // Image will be repeated all over
+ *  // Image would be repeated all over the chart, the position is irrelevant
  *  $chart->background->repeat = ezcGraph::HORIZONTAL | ezcGraph::VERTICAL;
- *      // The position is not relevant here.
+ *
+ *  $graph->render( 400, 250, 'legend.svg' );
  * </code>
  *
  * @property string $image
diff --git a/src/element/legend.php b/src/element/legend.php
index 7063fda..17e2f53 100644
--- a/src/element/legend.php
+++ b/src/element/legend.php
@@ -10,6 +10,47 @@
 /**
  * Class to represent a legend as a chart element
  *
+ * Chart elements can be understood as widgets or layout container inside the
+ * chart. The actual transformation to images happens inside the renderers.
+ * They represent all elements inside the chart and contain mostly general
+ * formatting options, while the renderer itself might define additional
+ * formatting options for some chart elments. You can find more about the
+ * general formatting options for chart elements in the base class
+ * ezcGraphChartElement.
+ *
+ * The legend chart element is used to display the legend of a chart. It can be
+ * deactivated by setting the legend to false, like:
+ *
+ * <code>
+ *  $chart->legend = false;
+ * </code>
+ *
+ * The position of the legend in the chart can be influenced by the postion
+ * property, set to one of the position constants from the ezcGraph base class,
+ * like ezcGraph::BOTTOM, ezcGraph::LEFT, ezcGraph::RIGHT, ezcGraph::TOP.
+ *
+ * Depending on the position of the legend, either the $portraitSize (RIGHT,
+ * LEFT) or the $landscapeSize (TOP, BOTTOM) defines how much space will be
+ * aqquired for the legend.
+ *
+ * <code>
+ *  $graph = new ezcGraphPieChart();
+ *  $graph->data['example'] = new ezcGraphArrayDataSet( array(
+ *      'Foo' => 23,
+ *      'Bar' => 42,
+ *  ) );
+ *  
+ *  // Format the legend element
+ *  $graph->legend->background    = '#FFFFFF80';
+ *
+ *  // Place at the bottom of the chart, with a height of 5% of the remaining
+ *  // chart space.
+ *  $graph->legend->position      = ezcGraph::BOTTOM;
+ *  $graph->legend->landscapeSize = .05;
+ *  
+ *  $graph->render( 400, 250, 'legend.svg' );
+ * </code>
+ *
  * @property float $portraitSize
  *           Size of a portrait style legend in percent of the size of the 
  *           complete chart.
diff --git a/src/element/text.php b/src/element/text.php
index 2fc219a..96cf80b 100644
--- a/src/element/text.php
+++ b/src/element/text.php
@@ -10,6 +10,34 @@
 /**
  * Chart element to display texts in a chart
  *
+ * Chart elements can be understood as widgets or layout container inside the
+ * chart. The actual transformation to images happens inside the renderers.
+ * They represent all elements inside the chart and contain mostly general
+ * formatting options, while the renderer itself might define additional
+ * formatting options for some chart elments. You can find more about the
+ * general formatting options for chart elements in the base class
+ * ezcGraphChartElement.
+ *
+ * The text element can only be placed at the top or the bottom of the chart.
+ * Beside the common options it has only one additional option defining the
+ * maximum height used for the text box. The actaully required height is
+ * calculated based on the assigned text size.
+ *
+ * <code>
+ *  $chart = new ezcGraphPieChart();
+ *  $chart->data['example'] = new ezcGraphArrayDataSet( array(
+ *      'Foo' => 23,
+ *      'Bar' => 42,
+ *  ) );
+ *
+ *  $chart->title = 'Some pie chart';
+ *
+ *  // Use at maximum 5% of the chart height for the title.
+ *  $chart->title->maxHeight = .05;
+ *
+ *  $graph->render( 400, 250, 'title.svg' );
+ * </code>
+ *
  * @property float $maxHeight
  *           Maximum percent of bounding used to display the text.
  *
diff --git a/src/exceptions/flash_bitmap_type.php b/src/exceptions/flash_bitmap_type.php
index ed07baa..9aa30b3 100644
--- a/src/exceptions/flash_bitmap_type.php
+++ b/src/exceptions/flash_bitmap_type.php
@@ -8,8 +8,8 @@
  * @license http://ez.no/licenses/new_bsd New BSD License
  */
 /**
- * Flash can only read non interlaced bitmaps. This exception is thrown for 
- * all other image types.
+ * Flash can only embed JPEGs and PNGs. This exception is thrown for * all
+ * other image types.
  *
  * @package Graph
  * @version //autogentag//
diff --git a/src/interfaces/axis_label_renderer.php b/src/interfaces/axis_label_renderer.php
index 4f925ee..9a5f064 100644
--- a/src/interfaces/axis_label_renderer.php
+++ b/src/interfaces/axis_label_renderer.php
@@ -11,6 +11,8 @@
  * Abstract class to render labels and grids on axis. Will be extended to
  * make it possible using different algorithms for rendering axis labels.
  *
+ * Implements basic methods to render the grid and steps on a axis.
+ *
  * @property bool $majorStepCount
  *           Count of major steps.
  * @property bool $minorStepCount
@@ -435,4 +437,5 @@ abstract class ezcGraphAxisLabelRenderer extends ezcBaseOptions
         ezcGraphChartElementAxis $axis
     );
 }
+
 ?>
diff --git a/src/interfaces/dataset_property.php b/src/interfaces/dataset_property.php
index 3d427ff..ebc9a4c 100644
--- a/src/interfaces/dataset_property.php
+++ b/src/interfaces/dataset_property.php
@@ -10,6 +10,36 @@
 /**
  * Abstract class for properties of datasets
  *
+ * This class is used to extends datasets with additional properties, and
+ * stores only non default values for each data point in a data set.
+ * 
+ * The class is extended by property implementations including simple value
+ * validators, like:
+ *
+ * - ezcGraphDataSetAxisProperty
+ * - ezcGraphDataSetBooleanProperty
+ * - ezcGraphDataSetColorProperty
+ * - ezcGraphDataSetIntProperty
+ * - ezcGraphDataSetStringProperty
+ *
+ * The color property can for example be accessed in a chart like:
+ *
+ * <code>
+ *  $graph = new ezcGraphLineChart();
+ *  $graph->data['example'] = new ezcGraphArrayDataSet( array(
+ *      'Foo' => 23,
+ *      'Bar' => 42,
+ *  ) );
+ *
+ *  // Set color for all data points in this data set
+ *  $graph->data['example']->color = '#a40000';
+ *
+ *  // Set different color for one special datapoint
+ *  $graph->data['example']->color['Foo'] = '#2e3436';
+ *
+ *  $graph->render( 400, 200, 'test.svg' );
+ * </code>
+ *
  * @version //autogentag//
  * @package Graph
  */
diff --git a/src/interfaces/element.php b/src/interfaces/element.php
index 6c6c93e..21bc576 100644
--- a/src/interfaces/element.php
+++ b/src/interfaces/element.php
@@ -7,9 +7,71 @@
  * @copyright Copyright (C) 2005-2008 eZ systems as. All rights reserved.
  * @license http://ez.no/licenses/new_bsd New BSD License
  */
+
 /**
- * Class for basic chart elements
+ * Base class for chart elements
+ *
+ * The base class for chart elements. Chart elements can be understood as
+ * widgets or layout container inside the chart. The actual transformation to
+ * images happens inside the renderers. They represent all elements inside the
+ * chart and contain mostly general formatting options, while the renderer
+ * itself might define additional formatting options for some chart elments.
+ *
+ * Important chart elements for example are:
+ *
+ * - Chart title (ezcGraphChartElementText)
+ * - Chart legend (ezcGraphChartElementLegend)
+ * - The axis (ezcGraphChartElementNumericAxis,
+ *   ezcGraphChartElementLogarithmicalAxis, ezcGraphChartElementLabeledAxis,
+ *   ezcGraphChartElementDateAxis)
+ * - ...
  * 
+ * The position of chart elements is defined in the $position property. The
+ * effect this has on the visual representation depends on the actual type of
+ * the chart element.
+ *
+ * Each chart element may be configured with options similar to CSS, used with
+ * HTML to define the general style of the repsective element:
+ *
+ * - $padding & $margin defne the distance of the border from inner elements /
+ *   other chart elements.
+ * - $borderWidth & $border define the style of the border used around the
+ *   chart element
+ * - $background defines the background color of the chart element. As always
+ *   this may be a (semi-) transparent color.
+ *
+ * A typical example with some layout for the chart title element could look
+ * like:
+ *
+ * <code>
+ *  $graph = new ezcGraphPieChart();
+ *  $graph->data['example'] = new ezcGraphArrayDataSet( array(
+ *      'Foo' => 23,
+ *      'Bar' => 42,
+ *  ) );
+ *  
+ *  // Set a title and format the title element
+ *  $graph->title              = 'Example formatted pie chart';
+ *  $graph->title->margin      = 2;
+ *  $graph->title->background  = '#FFFFFF80';
+ *  $graph->title->border      = '#FFFFFF';
+ *  $graph->title->borderWidth = 1;
+ *  $graph->title->margin      = 1;
+ *  $graph->title->padding     = 1;
+ *  
+ *  // Format the legend element
+ *  $graph->legend->margin      = 2;
+ *  $graph->legend->background  = '#FFFFFF80';
+ *  $graph->legend->border      = '#FFFFFF';
+ *  $graph->legend->borderWidth = 1;
+ *  $graph->legend->margin      = 1;
+ *  $graph->legend->padding     = 1;
+ *  
+ *  $graph->background->background = '#888a85';
+ *  
+ *  $graph->render( 400, 250, 'element.svg' );
+ * </code>
+ *
  * @property string $title
  *           Title of chart element.
  * @property ezcGraphColor $background