- More documentation improvements

  # There is still some way to go...

18 files changed, 229 insertions, 40 deletions

diff --git a/docs/img/tutorial_chart_font_configuration.svg.png b/docs/img/tutorial_chart_font_configuration.svg.png
new file mode 100644
index 0000000..704557d
--- /dev/null
+++ b/docs/img/tutorial_chart_font_configuration.svg.png
diff --git a/docs/tutorial.txt b/docs/tutorial.txt
index fc862f1..e6d5126 100644
--- a/docs/tutorial.txt
+++ b/docs/tutorial.txt
@@ -449,8 +449,7 @@ Chart elements
 ==============
 
 The chart elements all extend ezcGraphChartElement. Each of the elements can be
-configured independently. A default chart consists of
-the following elements:
+configured independently. A default chart consists of the following elements:
 
 - title
 - background
@@ -474,7 +473,16 @@ for each chart element.
 The solution is that you can modify the global font configuration by
 accessing $graph->options->font. This takes effect on all chart elements
 unless you intentionally access the font configuration of an individual chart
-element. The following section shows an example of this.
+element. The following example shows how this works.
+
+.. include:: tutorial/tutorial_chart_font_configuration.php
+   :literal:
+
+The output of the example shows, that all texts are using a serif font, while
+the title still stays with the default sans-serif font.
+
+.. image:: img/tutorial_chart_font_configuration.svg.png
+   :alt:   Font configuration in pie chart
 
 The chart title
 ---------------
diff --git a/docs/tutorial/tutorial_chart_font_configuration.php b/docs/tutorial/tutorial_chart_font_configuration.php
new file mode 100644
index 0000000..a564f62
--- /dev/null
+++ b/docs/tutorial/tutorial_chart_font_configuration.php
@@ -0,0 +1,29 @@
+<?php
+
+require_once 'tutorial_autoload.php';
+
+$graph = new ezcGraphPieChart();
+$graph->palette = new ezcGraphPaletteEzBlue();
+$graph->title = 'Access statistics';
+
+// Set the maximum font size to 8 for all chart elements
+$graph->options->font->maxFontSize = 8;
+
+// Set the font size for the title independently to 14
+$graph->title->font->maxFontSize = 14;
+
+// The following only affects all elements except the // title element,
+// which now has its own font configuration.
+$graph->options->font->name = 'serif';
+
+$graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
+    'Mozilla' => 19113,
+    'Explorer' => 10917,
+    'Opera' => 1464,
+    'Safari' => 652,
+    'Konqueror' => 474,
+) );
+
+$graph->render( 400, 150, 'tutorial_chart_font_configuration.svg' );
+
+?>
diff --git a/src/math/boundings.php b/src/math/boundings.php
index 825700f..f88f4b2 100644
--- a/src/math/boundings.php
+++ b/src/math/boundings.php
@@ -14,6 +14,10 @@
  * Currently only works with plane rectangular boundings, should be enhanced by
  * rotated rectangular boundings.
  *
+ * This class is only used internally to represent space which is used by
+ * certain obejcts on the drawing plane, or which free space is still
+ * available.
+ *
  * @version //autogentag//
  * @package Graph
  * @access private
diff --git a/src/math/rotation.php b/src/math/rotation.php
index bbc4f1e..12ddd44 100644
--- a/src/math/rotation.php
+++ b/src/math/rotation.php
@@ -11,6 +11,15 @@
 /**
  * Class to create rotation matrices from given rotation and center point
  *
+ * Three dimensional matrices (3x3) may be used to specify transformation of
+ * points, vectors and complexer structures in a two dimensional cartesian
+ * coordinate system. For more details have a look here:
+ * http://en.wikipedia.org/wiki/Transformation_matrix
+ *
+ * This class implements a convenient interface to create matrixes to rotate
+ * elements. This matrix may be combined with other transformation matrices, as
+ * usual.
+ *
  * @version //autogentag//
  * @package Graph
  * @access private
diff --git a/src/math/transformation.php b/src/math/transformation.php
index 78b95f1..a1ed70b 100644
--- a/src/math/transformation.php
+++ b/src/math/transformation.php
@@ -9,8 +9,19 @@
  * @access private
  */
 /**
- * Class defining transformations like scaling and rotation by a 
- * 3x3 transformation matrix for |R^2
+ * Class defining transformations
+ *
+ * Three dimensional matrices (3x3) may be used to specify transformation of
+ * points, vectors and complexer structures in a two dimensional cartesian
+ * coordinate system. For more details have a look here:
+ * http://en.wikipedia.org/wiki/Transformation_matrix
+ *
+ * There are some classes extending this basic tranformation class, to
+ * give you more convinient access to the creation of such transformation
+ * matrices, which are:
+ * 
+ * - ezcGraphRotation (rotations of objects)
+ * - ezcGraphTranslation (moving of objects)
  *
  * @version //autogentag//
  * @package Graph
diff --git a/src/math/translation.php b/src/math/translation.php
index ca22063..a9b1c3c 100644
--- a/src/math/translation.php
+++ b/src/math/translation.php
@@ -11,6 +11,15 @@
 /**
  * Class creating translation matrices from given movements
  *
+ * Three dimensional matrices (3x3) may be used to specify transformation of
+ * points, vectors and complexer structures in a two dimensional cartesian
+ * coordinate system. For more details have a look here:
+ * http://en.wikipedia.org/wiki/Transformation_matrix
+ *
+ * This class implements a convenient interface to create matrixes to move
+ * elements. This matrix may be combined with other transformation matrices, as
+ * usual.
+ *
  * @version //autogentag//
  * @package Graph
  * @access private
diff --git a/src/math/vector.php b/src/math/vector.php
index 9415bca..c34b34d 100644
--- a/src/math/vector.php
+++ b/src/math/vector.php
@@ -11,6 +11,13 @@
 /**
  * Represents two dimensional vectors
  *
+ * This class is internally used to represent vectors for geometric calculation
+ * in the two dimensional cartesian coordinate system.
+ *
+ * Vectors are an extension of the basic coordinate class, and add methods to
+ * calculate the length of a vector, perform various operations on angles, like
+ * rotations and the calculation of angles between two vectors.
+ *
  * @version //autogentag//
  * @package Graph
  * @access private
diff --git a/src/options/driver.php b/src/options/driver.php
index 5253f25..80e2025 100644
--- a/src/options/driver.php
+++ b/src/options/driver.php
@@ -10,6 +10,15 @@
 /**
  * Class containing the basic driver options.
  *
+ * Most of the options of the driver class, like the width, height and font are
+ * set internally by the driver and not really relevant to the user of driver
+ * classes. You can configure how strings are automatically shortened, together
+ * with the postfix, which is appended to shortened strings, like the following
+ * example shows.
+ *
+ * Configuration options, which special to the actual drivers are configured in
+ * the driver specific extensions of this option class.
+ * 
  * <code>
  *   require_once 'tutorial_autoload.php';
  *   
@@ -25,6 +34,8 @@
  *       'Konqueror' => 474,
  *   ) );
  *
+ *   // Do not shorten strings automatically if they do not fit in the assigned
+ *   // space with the minimum font size.
  *   $graph->driver->options->autoShortenString = false;
  *   
  *   $graph->render( 400, 150, 'tutorial_chart_title.svg' );
@@ -41,9 +52,13 @@
  * @property int $font
  *           Font used in the graph.
  * @property bool $autoShortenString
- *           Automatically shorten string if it does not fit into a box
+ *           Automatically shorten string if it do not fit into the available
+ *           space, even with the minimum font size used. Deactivating this
+ *           setting will result in ezcGraphFontRenderingException exceptions,
+ *           informing you about the actual string which did not fit.
  * @property string $autoShortenStringPostFix
  *           String to append to shortened strings, if there is enough space
+ *           left for the postfix.
  *
  * @version //autogentag//
  * @package Graph
diff --git a/src/options/flash_driver.php b/src/options/flash_driver.php
index 8d34c3f..9bf24b4 100644
--- a/src/options/flash_driver.php
+++ b/src/options/flash_driver.php
@@ -10,6 +10,10 @@
 /**
  * Class containing the extended configuration options for the flash driver.
  *
+ * The flash driver can be configured to use a different circle resolution, as
+ * circles are only emulated in the flash driver, and to use a diffrent
+ * compression for the generated SWF files.
+ *
  * <code>
  *   $graph = new ezcGraphPieChart();
  *   $graph->title = 'Access statistics';
diff --git a/src/options/font.php b/src/options/font.php
index 358659a..6d13eb0 100644
--- a/src/options/font.php
+++ b/src/options/font.php
@@ -10,32 +10,37 @@
 /**
  * Class containing the options for font configuration.
  *
- * Global font settings will only affect the font settings of chart elements
- * until they were modified once. Form then on the font configuration of one
- * chart element has been copied and can only be configured independently.
+ * We try to fulfill two goals regarding font configuration. First, there
+ * should be a single point to configure the fonts used for the text areas
+ * in the chart.  On the other hand, it should be possible to configure
+ * the fonts independently for each chart element.
+ *
+ * The solution is that you can modify the global font configuration by
+ * accessing $graph->options->font. This takes effect on all chart
+ * elements unless you intentionally access the font configuration of an
+ * individual chart element. The following example shows, how this works.
  *
  * <code>
- *   $graph = new ezcGraphPieChart();
- *   $graph->palette = new ezcGraphPaletteEzBlue();
- *   $graph->title = 'Access statistics';
- *   
- *   $graph->options->font->name = 'serif';
- *   $graph->options->font->maxFontSize = 12;
- *   
- *   $graph->title->background = '#EEEEEC';
- *   $graph->title->font->name = 'sans-serif';
- *   
- *   $graph->options->font->maxFontSize = 8;
- *   
- *   $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
- *       'Mozilla' => 19113,
- *       'Explorer' => 10917,
- *       'Opera' => 1464,
- *       'Safari' => 652,
- *       'Konqueror' => 474,
- *   ) );
- *   
- *   $graph->render( 400, 150, 'tutorial_chart_title.svg' );
+ *  $graph = new ezcGraphPieChart();
+ *  $graph->title = 'Access statistics';
+ *
+ *  // Set the maximum font size to 8 for all chart elements
+ *  $graph->options->font->maxFontSize = 8;
+ *
+ *  // Set the font size for the title independently to 14
+ *  $graph->title->font->maxFontSize = 14;
+ *
+ *  // The following only affects all elements except the // title element,
+ *  // which now has its own font configuration.
+ *  $graph->options->font->name = 'serif';
+ *
+ *  $graph->data['Access statistics'] = new ezcGraphArrayDataSet( array(
+ *      'Mozilla' => 19113,
+ *      'Explorer' => 10917,
+ *      'Opera' => 1464,
+ *      'Safari' => 652,
+ *      'Konqueror' => 474,
+ *  ) );
  * </code>
  *
  * @property string $name
@@ -47,32 +52,43 @@
  *            - TTF_FONT    Native TTF fonts
  *            - PS_FONT     PostScript Type1 fonts
  *            - FT2_FONT    FreeType 2 fonts
+ *           The type is normally automatically detected when you set the path
+ *           to the font file.
  * @property float $minFontSize
  *           Minimum font size for displayed texts.
  * @property float $maxFontSize
  *           Maximum font size for displayed texts.
  * @property float $minimalUsedFont
- *           The minimal used font size for this element.
+ *           The minimal used font size for the current element group. This
+ *           property is set by the driver to maintain this information and
+ *           should not be used to configure the apperance of the chart. See
+ *           $minFontSize instead.
  * @property ezcGraphColor $color
  *           Font color.
  * @property ezcGraphColor $background
- *           Background color
+ *           Background color. The actual area filled with the background color
+ *           is influenced by the settings $padding and $minimizeBorder.
  * @property ezcGraphColor $border
- *           Border color
+ *           Border color for the text. The distance between the text and
+ *           border is defined by the properties $padding and $minimizeBorder.
  * @property int $borderWidth
- *           Border width
+ *           With of the border. To enable the border you need to set the
+ *           $border property to some color.
  * @property int $padding
- *           Padding between text and border
+ *           Padding between text and border.
  * @property bool $minimizeBorder
  *           Fit the border exactly around the text, or use the complete 
- *           possible space.
+ *           possible space. This setting is only relevant, when a border
+ *           color has been set for the font.
  * @property bool $textShadow
- *           Draw shadow for texts
+ *           Draw shadow for texts. The color of the shadow is defined in
+ *           the property $textShadowColor.
  * @property int $textShadowOffset
- *           Offset for text shadow
+ *           Offset for text shadow. This defines the distance the shadow
+ *           is moved to the bottom left relative from the text position.
  * @property ezcGraphColor $textShadowColor
- *           Color of text shadow. If false the inverse color of the text 
- *           color will be used.
+ *           Color of text shadow. If left at the default value "false""
+ *           the inverse color of the text color will be used.
  *
  * @version //autogentag//
  * @package Graph
diff --git a/src/options/line_chart.php b/src/options/line_chart.php
index 0ccb09f..fa963dd 100644
--- a/src/options/line_chart.php
+++ b/src/options/line_chart.php
@@ -10,6 +10,17 @@
 /**
  * Class containing the basic options for line charts.
  *
+ * This class contains basic options relevant for line and bar charts, which
+ * are just an extension of line charts.
+ *
+ * For additional options configuring the apperance of the chart you may also
+ * want to check the option classes to configure the respective renderer you
+ * are using:
+ *
+ * - ezcGraphRendererOptions
+ * - ezcGraphRenderer2dOptions
+ * - ezcGraphRenderer3dOptions
+ *
  * <code>
  *   $graph = new ezcGraphLineChart();
  *   $graph->title = 'Wikipedia articles';
diff --git a/src/options/pie_chart.php b/src/options/pie_chart.php
index 070acaa..da7c676 100644
--- a/src/options/pie_chart.php
+++ b/src/options/pie_chart.php
@@ -10,6 +10,14 @@
 /**
  * Class containing the basic options for pie charts.
  *
+ * For additional options configuring the apperance of the chart you may also
+ * want to check the option classes to configure the respective renderer you
+ * are using:
+ *
+ * - ezcGraphRendererOptions
+ * - ezcGraphRenderer2dOptions
+ * - ezcGraphRenderer3dOptions
+ *
  * <code>
  *   $graph = new ezcGraphPieChart();
  *   $graph->palette = new ezcGraphPaletteEzRed();
diff --git a/src/options/renderer.php b/src/options/renderer.php
index 7245f60..a896767 100644
--- a/src/options/renderer.php
+++ b/src/options/renderer.php
@@ -10,6 +10,16 @@
 /**
  * Class containing the basic options for renderers.
  *
+ * Renderer options are used to define the general appearance of charts beside
+ * the palettes. The renderer transforms chart primitives (like the legend, or
+ * one pie slice) into image primitives, which are then rendered by the
+ * drivers. The way this transformation is done, and which effects are also
+ * rendered is specified by the values in this option class. 
+ *
+ * The example below shows some basic bar rendering options, which are
+ * available in all renderers. You mya want to check the tutorial sections
+ * about the renderer, which show example output for more renderer options.
+ *
  * <code>
  *   $wikidata = include 'tutorial_wikipedia_data.php';
  *   
@@ -32,6 +42,21 @@
  *   $graph->render( 400, 150, 'tutorial_bar_chart_options.svg' );
  * </code>
  *
+ * For additional options, which are special to some chart type you may
+ * also want to check the option classes for the repective chart type you
+ * are using and the elements of the chart. The chart type dependant option
+ * classes are:
+ *
+ * - ezcGraphLineChartOptions
+ * - ezcGraphPieChartOptions
+ * - ezcGraphRadarChartOptions
+ *
+ * There may be additional options dependant on the renderer you are using.
+ * You may want to check the extensions of this class:
+ *
+ * - ezcGraphRenderer2dOptions
+ * - ezcGraphRenderer3dOptions
+ *
  * @property float $maxLabelHeight
  *           Percent of chart height used as maximum height for pie chart 
  *           labels.
diff --git a/src/options/renderer_3d.php b/src/options/renderer_3d.php
index 8cc485b..48262c7 100644
--- a/src/options/renderer_3d.php
+++ b/src/options/renderer_3d.php
@@ -10,6 +10,10 @@
 /**
  * Class containing the extended options for the three dimensional renderer.
  *
+ * The three dimensional renderer offers a visually improved rendering compared
+ * with the two dimensional renderer. This results in more options configuring
+ * the three dimensional effeks, shadows and gleams in the chart.
+ *
  * <code>
  *   $graph = new ezcGraphPieChart();
  *   $graph->palette = new ezcGraphPaletteEzRed();
diff --git a/src/structs/context.php b/src/structs/context.php
index 370d583..60eefa7 100644
--- a/src/structs/context.php
+++ b/src/structs/context.php
@@ -7,9 +7,25 @@
  * @copyright Copyright (C) 2005-2008 eZ systems as. All rights reserved.
  * @license http://ez.no/licenses/new_bsd New BSD License
  */
+
 /**
  * Struct to represent the context of a renderer operation
  *
+ * Objects of this class are passed to the renderer, so the renderer is able to
+ * maintain the associations between image primitives and the datpoints. With
+ * this information the renderer build the array returned by the
+ * getElementReferences() method of the ezcGraphRenderer classes. In the
+ * returned array the datapoints are then associated with the identifiers for
+ * the image primitives returned by the respective driver.
+ *
+ * The ezcGraphTools class offers convience methods to handle this data and
+ * enrich your charts with hyperlinks, so you don't need to handle this
+ * yourself.
+ *
+ * The struct contains information about the $dataset and $datapoint the
+ * image primitive is associated with. If the dataset or datapoint has an
+ * URL associated, this URL is also available in the context struct.
+ *
  * @version //autogentag//
  * @package Graph
  */
diff --git a/src/structs/coordinate.php b/src/structs/coordinate.php
index 172320e..9040b21 100644
--- a/src/structs/coordinate.php
+++ b/src/structs/coordinate.php
@@ -10,6 +10,12 @@
 /**
  * Represents coordinates in two dimensional catesian coordinate system.
  *
+ * Coordinates are used to represent the location of objects on the drawing
+ * plane. They are simple structs conatining the two coordinate values required
+ * in a two dimensional cartesian coordinate system. The class ezcGraphVector
+ * extends the Coordinate class and provides additional methods like rotations,
+ * simple arithmetic operations etc.
+ *
  * @version //autogentag//
  * @package Graph
  */
diff --git a/src/structs/step.php b/src/structs/step.php
index 8cfd73f..50bc6d3 100644
--- a/src/structs/step.php
+++ b/src/structs/step.php
@@ -10,6 +10,13 @@
 /**
  * Represents a single step on the axis
  *
+ * Struct class containg information for single steps in the axis. A step may
+ * have child steps, which are commonly known as major (bigger) and minor
+ * (smaller) steps on axis.
+ *
+ * The positions of multiple steps in an array generated by the
+ * ezcGraphChartElementAxis classes is not always distributed evenly.
+ *
  * @version //autogentag//
  * @package Graph
  */