Added doc notes for classes and methods used for the scaling automatism.

3 files changed, 104 insertions, 3 deletions

diff --git a/chart2/source/view/inc/ScaleAutomatism.hxx b/chart2/source/view/inc/ScaleAutomatism.hxx
index 3518eb2bae64..17370fb4a5da 100644
--- a/chart2/source/view/inc/ScaleAutomatism.hxx
+++ b/chart2/source/view/inc/ScaleAutomatism.hxx
@@ -28,7 +28,15 @@ namespace chart
 {
 
 /** This class implements the calculation of automatic axis limits.
-*/
+ *
+ *  This class is used for calculating axis scales and increments in the form
+ *  of instances of `ExplicitScaleData` and `ExplicitIncrementData` classes.
+ *  When a `ScaleAutomatism` instance is created a `ScaleData` object is passed
+ *  to the constructor. Objects of `ScaleData` type are initialized by
+ *  the `createCoordinateSystem` method of some chart type (e.g.
+ *  the `PieChartType` class) and belong to some `Axis` object, they can be
+ *  accessed through the `XAxis` interface (`XAxis::getScaleData`).
+ */
 class ScaleAutomatism
 {
 public:
@@ -36,7 +44,14 @@ public:
                             const ::com::sun::star::chart2::ScaleData& rSourceScale, const Date& rNullDate );
     virtual             ~ScaleAutomatism();
 
-    /** Expands own value range with the passed minimum and maximum. */
+    /** Expands own value range with the passed minimum and maximum.
+     *
+     *  It allows to set up the `m_fValueMinimum` and the `m_fValueMaximum`
+     *  parameters which are used by the `calculateExplicitScaleAndIncrement`
+     *  method for initializing the `Minimum` and `Maximum` properties of the
+     *  explicit scale when the same properties of the `ScaleData` object are
+     *  undefined (that is empty `uno::Any` objects).
+     */
     void                expandValueRange( double fMinimum, double fMaximum );
 
     /** Sets additional auto scaling options.
@@ -68,7 +83,14 @@ public:
     */
     void setAutomaticTimeResolution( sal_Int32 nTimeResolution );
 
-    /** Fills the passed scale data and increment data according to the own settings. */
+    /** Fills the passed scale data and increment data according to the own settings.
+     *
+     *  It performs the initialization of the passed explicit scale and
+     *  explicit increment parameters, mainly the initialization is achieved by
+     *  using the `ScaleData` object as data source. However other parameters
+     *  which affect the behavior of this method can be set through
+     *  the `setAutoScalingOptions` and the `expandValueRange` methods.
+     */
     void                calculateExplicitScaleAndIncrement(
                             ExplicitScaleData& rExplicitScale,
                             ExplicitIncrementData& rExplicitIncrement ) const;
diff --git a/chart2/source/view/inc/VCoordinateSystem.hxx b/chart2/source/view/inc/VCoordinateSystem.hxx
index 645149edf498..291c1a2c1c64 100644
--- a/chart2/source/view/inc/VCoordinateSystem.hxx
+++ b/chart2/source/view/inc/VCoordinateSystem.hxx
@@ -86,6 +86,20 @@ public:
     bool hasMinimumAndMaximumSupplier( MinimumAndMaximumSupplier* pMinimumAndMaximumSupplier );
     void clearMinimumAndMaximumSupplierList();
 
+    /**
+     * It sets the scaling parameters for the passed `ScaleAutomatism` object.
+     * Especially it sets the `m_fValueMinimum` and the `m_fValueMaximum`
+     * parameters (see `ScaleAutomatism::expandValueRange`).
+     * The value to be assigned to these two parameters is retrieved by
+     * invoking the `getMinimum` and `getMaximum` methods of the minimum-maximum
+     * supplier object that belongs to the given coordinate system.
+     * The minimum-maximum supplier object is set in the
+     * `SeriesPlotterContainer::initializeCooSysAndSeriesPlotter` method to the
+     * series plotter which is based on the coordinate system (see notes for
+     * the method). For instance for a pie chart the `m_fValueMinimum` and the
+     * `m_fValueMaximum` parameters are initialized by the `PieChart::getMinimum`
+     * and `PieChart::getMaximum` methods.
+     */
     void prepareAutomaticAxisScaling( ScaleAutomatism& rScaleAutomatism, sal_Int32 nDimIndex, sal_Int32 nAxisIndex );
 
     void setExplicitScaleAndIncrement( sal_Int32 nDimensionIndex, sal_Int32 nAxisIndex
diff --git a/chart2/source/view/main/ChartView.cxx b/chart2/source/view/main/ChartView.cxx
index ce183f972154..ebec017e2ef3 100644
--- a/chart2/source/view/main/ChartView.cxx
+++ b/chart2/source/view/main/ChartView.cxx
@@ -133,6 +133,15 @@ class theExplicitValueProviderUnoTunnelId  : public rtl::Static<UnoTunnelIdInit,
 typedef std::pair< sal_Int32, sal_Int32 > tFullAxisIndex; //first index is the dimension, second index is the axis index that indicates whether this is a main or secondary axis
 typedef std::map< VCoordinateSystem*, tFullAxisIndex > tCoordinateSystemMap;
 
+/** This class handles a collection of coordinate systems and is used for
+ *  executing some action on all coordinate systems such as
+ *  `prepareAutomaticAxisScaling` and `setExplicitScaleAndIncrement`.
+ *  Moreover it contains the `aAutoScaling` object that is an instance of
+ *  the `ScaleAutomatism` class. The initialization of `aAutoScaling` is
+ *  performed in the `SeriesPlotterContainer::initAxisUsageList` method and is
+ *  used in the `SeriesPlotterContainer::doAutoScaling` for calculating explicit
+ *  scale and increment objects (see `SeriesPlotterContainer::doAutoScaling`).
+ */
 struct AxisUsage
 {
     AxisUsage();
@@ -241,13 +250,45 @@ void AxisUsage::setExplicitScaleAndIncrement(
 
 typedef boost::ptr_vector<VSeriesPlotter> SeriesPlottersType;
 
+/** This class is a container of `SeriesPlotter` objects (such as `PieChart`
+ *  instances). It is used for initializing coordinate systems, axes and scales
+ *  of all series plotters which belongs to the container.
+ */
 class SeriesPlotterContainer
 {
 public:
     SeriesPlotterContainer( std::vector< VCoordinateSystem* >& rVCooSysList );
     ~SeriesPlotterContainer();
 
+    /** It is used to set coordinate systems (`m_rVCooSysList`), this method
+     *  is invoked by `ChartView::createShapes2D` before of
+     *  `ChartView::impl_createDiagramAndContent`.
+     *  Coordinate systems are retrieved through the `XCoordinateSystemContainer`
+     *  interface implemented by a diagram object which is provided by the
+     *  `ChartModel` object passed to the method (`rChartModel.getFirstDiagram()`).
+     *
+     *  It is used for creating series plotters and appending them
+     *  to `m_aSeriesPlotterList`. The created series plotters are initialized
+     *  through data (number formats supplier, color scheme, data series),
+     *  extracted from the chart model or the diagram objects. An exception is
+     *  the explicit category provider that is retrieved through the
+     *  `VCoordinateSystem` object used by the series plotter.
+     *
+     *  It sets the minimum-maximum supplier for a coordinate system:
+     *  this supplier is the series plotter itself which utilizes the given
+     *  coordinate system. In fact `VSeriesPlotter` has `MinimumMaximumSupplier`
+     *  as one of its base classes.
+     *  Hence, for instance, a `PieChart`, which is a series plotter, is
+     *  a `MinimumMaximumSupplier`, too.
+     */
     void initializeCooSysAndSeriesPlotter( ChartModel& rModel );
+
+    /** This method is invoked by `ChartView::impl_createDiagramAndContent`.
+     *  It iterates on every axis of every coordinate systems, and if the axis
+     *  is not yet present in `m_aAxisUsageList` it creates a new `AxisUsage`
+     *  object and initialize its `aAutoScaling` member to the `ScaleData`
+     *  object of the current axis.
+     */
     void initAxisUsageList(const Date& rNullDate);
 
     /**
@@ -258,6 +299,21 @@ public:
      * The new axis scaling data will be stored in the VCoordinateSystem
      * objects.  The label alignment direction for each axis will also get
      * determined during this process, and stored in VAxis.
+     *
+     * This method is invoked by `ChartView::impl_createDiagramAndContent`
+     * soon after `initAxisUsageList`.
+     * It initializes explicit scale and increment objects for all coordinate
+     * systems in `m_rVCooSysList`.
+     * This action is achieved by iterating on the `m_aAxisUsageList` container,
+     * and performing 3 steps:
+     *   1- call `VCoordinateSystem::prepareAutomaticAxisScaling` for setting
+     *      scaling parameters of the `aAutoScaling` member (a `ScaleAutomatism`
+     *      object) for the current `AxisUsage` instance
+     *      (see `VCoordinateSystem::prepareAutomaticAxisScaling`);
+     *   2- calculate the explicit scale and increment objects
+     *      (see ScaleAutomatism::calculateExplicitScaleAndIncrement);
+     *   3- set the explicit scale and increment objects for each coordinate
+     *      system.
      */
     void doAutoScaling( ChartModel& rModel );
 
@@ -286,8 +342,17 @@ public:
         const chart2::ScaleData& rSourceScale, bool bHasComplexCategories ) const;
 
 private:
+    /** A vector of series plotters.
+     */
     SeriesPlottersType m_aSeriesPlotterList;
+
+    /** A vector of coordinate systems.
+     */
     std::vector< VCoordinateSystem* >& m_rVCooSysList;
+
+    /** A map whose key is a `XAxis` interface and the related value is
+     *  an object of `AxisUsage` type.
+     */
     ::std::map< uno::Reference< XAxis >, AxisUsage > m_aAxisUsageList;
 
     /**