- Enhanced chart element documentation

4 files changed, 164 insertions, 9 deletions

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.
  *