Add documentation for data table added classes and functions

Change-Id: Idc9756bf5b468d8ed0d11e6a75703d96350e1273
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/139960
Tested-by: Jenkins
Reviewed-by: Tomaž Vajngerl <quikee@gmail.com>

15 files changed, 60 insertions, 6 deletions

diff --git a/chart2/source/controller/dialogs/tp_DataTable.hxx b/chart2/source/controller/dialogs/tp_DataTable.hxx
index a4ef6d6cf436..00ab64cf89ce 100644
--- a/chart2/source/controller/dialogs/tp_DataTable.hxx
+++ b/chart2/source/controller/dialogs/tp_DataTable.hxx
@@ -14,6 +14,7 @@
 
 namespace chart
 {
+/** Tab page for the data table properties */
 class DataTableTabPage : public SfxTabPage
 {
 private:
diff --git a/chart2/source/controller/inc/DataTableItemConverter.hxx b/chart2/source/controller/inc/DataTableItemConverter.hxx
index 5dbfaf60bba9..68c5790ba345 100644
--- a/chart2/source/controller/inc/DataTableItemConverter.hxx
+++ b/chart2/source/controller/inc/DataTableItemConverter.hxx
@@ -30,6 +30,7 @@ class SdrModel;
 
 namespace chart::wrapper
 {
+/** Convert data table properties to and from ItemSet and UNO PropertySet */
 class DataTableItemConverter final : public ItemConverter
 {
 public:
diff --git a/chart2/source/controller/inc/dlg_InsertDataTable.hxx b/chart2/source/controller/inc/dlg_InsertDataTable.hxx
index 346f7b651c24..cd77099864c4 100644
--- a/chart2/source/controller/inc/dlg_InsertDataTable.hxx
+++ b/chart2/source/controller/inc/dlg_InsertDataTable.hxx
@@ -14,6 +14,7 @@
 
 namespace chart
 {
+/** The data table properties (data) used by the dialog */
 struct DataTableDialogData
 {
     bool mbShow = true;
@@ -23,6 +24,7 @@ struct DataTableDialogData
     bool mbKeys = false;
 };
 
+/** The dialog to change the data table specific properties */
 class InsertDataTableDialog final : public weld::GenericDialogController
 {
 private:
@@ -38,7 +40,10 @@ private:
 public:
     InsertDataTableDialog(weld::Window* pParent);
 
+    /** Set the initial state of the data table properties */
     void init(DataTableDialogData const& rData);
+
+    /** Get the state of the data table properties from the dialog */
     DataTableDialogData& getDataTableDialogData();
 };
 
diff --git a/chart2/source/controller/inc/res_DataTableProperties.hxx b/chart2/source/controller/inc/res_DataTableProperties.hxx
index 299934cb0211..4b2aaa4f2ef7 100644
--- a/chart2/source/controller/inc/res_DataTableProperties.hxx
+++ b/chart2/source/controller/inc/res_DataTableProperties.hxx
@@ -14,6 +14,7 @@
 
 namespace chart
 {
+/** The shared UI elements for the data table properties */
 class DataTablePropertiesResources final
 {
 private:
diff --git a/chart2/source/controller/main/ChartController_Insert.cxx b/chart2/source/controller/main/ChartController_Insert.cxx
index 78005072a009..c75ac20457e5 100644
--- a/chart2/source/controller/main/ChartController_Insert.cxx
+++ b/chart2/source/controller/main/ChartController_Insert.cxx
@@ -235,6 +235,7 @@ void ChartController::executeDispatch_OpenInsertDataTableDialog()
     }
 }
 
+/** Create and insert a data table to the chart */
 void ChartController::executeDispatch_InsertDataTable()
 {
     auto aUndoDescription = ActionDescriptionProvider::createDescription(ActionDescriptionProvider::ActionType::Insert, SchResId(STR_DATA_TABLE));
@@ -254,16 +255,17 @@ void ChartController::executeDispatch_InsertDataTable()
     }
 }
 
+/** Delete a data table from the chart */
 void ChartController::executeDispatch_DeleteDataTable()
 {
     auto aUndoDescription = ActionDescriptionProvider::createDescription(ActionDescriptionProvider::ActionType::Delete, SchResId(STR_DATA_TABLE));
     UndoGuard aUndoGuard(aUndoDescription, m_xUndoManager);
 
-
     rtl::Reference<Diagram> xDiagram = getFirstDiagram();
     auto xDataTable = xDiagram->getDataTable();
     if (xDataTable.is())
     {
+        // insert a empty data table reference
         xDiagram->setDataTable(uno::Reference<chart2::XDataTable>());
         aUndoGuard.commit();
     }
diff --git a/chart2/source/inc/ObjectIdentifier.hxx b/chart2/source/inc/ObjectIdentifier.hxx
index b79a5fe9ca1e..14b684f59f46 100644
--- a/chart2/source/inc/ObjectIdentifier.hxx
+++ b/chart2/source/inc/ObjectIdentifier.hxx
@@ -150,6 +150,7 @@ public:
     static OUString createParticleForLegend(
         const rtl::Reference<::chart::ChartModel>& xChartModel );
 
+    /** Creates an identifier for the data table */
     static OUString createParticleForDataTable(
         const rtl::Reference<::chart::ChartModel>& xChartModel );
 
diff --git a/chart2/source/model/main/DataTable.cxx b/chart2/source/model/main/DataTable.cxx
index a81cc6dedf7a..d21febb14e47 100644
--- a/chart2/source/model/main/DataTable.cxx
+++ b/chart2/source/model/main/DataTable.cxx
@@ -25,6 +25,7 @@ using namespace css;
 
 namespace
 {
+/** DataTable Properties */
 enum
 {
     DataTableProperty_HorizontalBorder,
diff --git a/chart2/source/view/inc/DataTableView.hxx b/chart2/source/view/inc/DataTableView.hxx
index ba0a5f8d051d..0bccaaddde31 100644
--- a/chart2/source/view/inc/DataTableView.hxx
+++ b/chart2/source/view/inc/DataTableView.hxx
@@ -23,26 +23,43 @@ class VSeriesPlotter;
 class ChartModel;
 class LegendEntryProvider;
 
+/**
+ * DataTableView is responsible to create the table object, set the cell
+ * properties accordingly to the model and fill it with the chart series
+ * data.
+ */
 class DataTableView final
 {
 private:
     rtl::Reference<::chart::ChartModel> m_xChartModel;
+    // the target shape
     rtl::Reference<SvxShapeGroupAnyD> m_xTarget;
+    // the data table shape
     rtl::Reference<SvxTableShape> m_xTableShape;
+    // the data table model
     rtl::Reference<DataTable> m_xDataTableModel;
     css::uno::Reference<css::uno::XComponentContext> m_xComponentContext;
     css::uno::Reference<css::table::XTable> m_xTable;
     VLineProperties m_aLineProperties;
     std::vector<VSeriesPlotter*> m_pSeriesPlotterList;
 
+    // data series names
     std::vector<OUString> m_aDataSeriesNames;
+    // X axis names
     std::vector<OUString> m_aXValues;
+    // list of data series values
     std::vector<std::vector<OUString>> m_pDataSeriesValues;
+
+    // if the header vales should be aligned with the x-axis vales
     bool m_bAlignAxisValuesWithColumns;
 
+    /** Set the char and paragraph properties for the input (value) cell */
     void
     setCellCharAndParagraphProperties(css::uno::Reference<css::beans::XPropertySet>& xPropertySet);
 
+    /** Set the common cell properties (for all cells in the data table,
+     *  including headers)
+     */
     void setCellProperties(css::uno::Reference<css::beans::XPropertySet>& xPropertySet, bool bLeft,
                            bool bTop, bool bRight, bool bBottom);
 
@@ -51,10 +68,18 @@ public:
                   rtl::Reference<DataTable> const& rDataTableModel,
                   css::uno::Reference<css::uno::XComponentContext> const& rComponentContext,
                   bool bAlignAxisValuesWithColumns);
+
+    /** Initializes and prepares the target and data table shape */
     void initializeShapes(const rtl::Reference<SvxShapeGroupAnyD>& xTarget);
+
+    /** Prepares the values of the chart, which will be shown it the data table */
     void initializeValues(std::vector<std::unique_ptr<VSeriesPlotter>>& rSeriesPlotterList);
+
+    /** Creates the data table and fills the values */
     void createShapes(basegfx::B2DVector const& rStart, basegfx::B2DVector const& rEnd,
                       sal_Int32 nAxisStepWidth);
+
+    /** Repositions the data table shape */
     void changePosition(sal_Int32 x, sal_Int32 y);
 };
 
diff --git a/chart2/source/view/main/DataTableView.cxx b/chart2/source/view/main/DataTableView.cxx
index 45b199b59d69..c3c807ca099b 100644
--- a/chart2/source/view/main/DataTableView.cxx
+++ b/chart2/source/view/main/DataTableView.cxx
@@ -239,11 +239,13 @@ void DataTableView::createShapes(basegfx::B2DVector const& rStart, basegfx::B2DV
     if (!m_xTarget.is())
         return;
 
+    // Remove shapes first before we add the new ones
     ShapeFactory::removeSubShapes(m_xTarget);
     auto sParticle = ObjectIdentifier::createParticleForDataTable(m_xChartModel);
     auto sCID = ObjectIdentifier::createClassifiedIdentifierForParticle(sParticle);
     m_xTableShape = ShapeFactory::createTable(m_xTarget, sCID);
 
+    // calculate the table size
     auto rDelta = rEnd - rStart;
     sal_Int32 nTableSize = basegfx::fround(rDelta.getX());
     m_xTableShape->setSize({ nTableSize, 0 });
@@ -269,6 +271,7 @@ void DataTableView::createShapes(basegfx::B2DVector const& rStart, basegfx::B2DV
 
     auto* pTableObject = static_cast<sdr::table::SdrTableObj*>(m_xTableShape->GetSdrObject());
 
+    // get the data table properties from the model
     bool bHBorder = false;
     bool bVBorder = false;
     bool bOutline = false;
@@ -281,6 +284,7 @@ void DataTableView::createShapes(basegfx::B2DVector const& rStart, basegfx::B2DV
     m_xDataTableModel->getPropertyValue("Outline") >>= bOutline;
     m_xDataTableModel->getPropertyValue("Keys") >>= bKeys;
 
+    // set the data table row and column size
     sal_Int32 nColumnCount = m_aXValues.size();
     uno::Reference<table::XTableColumns> xTableColumns = m_xTable->getColumns();
     xTableColumns->insertByIndex(0, nColumnCount);
@@ -291,7 +295,8 @@ void DataTableView::createShapes(basegfx::B2DVector const& rStart, basegfx::B2DV
 
     sal_Int32 nColumnWidth = 0.0;
 
-    // If we don't align, we have to calculate the column width ourselves
+    // If we don't align, we have to calculate the column width ourselves,
+    // otherwise the column width is taken from the x-axis width
     if (m_bAlignAxisValuesWithColumns)
         nColumnWidth = nAxisStepWidth;
     else
@@ -452,11 +457,13 @@ void DataTableView::createShapes(basegfx::B2DVector const& rStart, basegfx::B2DV
 
     xBroadcaster->unlockBroadcasts();
 
+    // force recalculation of all cells in the table shape
     pTableObject->DistributeColumns(0, nColumnCount, true, true);
     pTableObject->DistributeRows(0, nRowCount, true, true);
 
     xBroadcaster->lockBroadcasts();
 
+    // reposition the data table
     changePosition(basegfx::fround(rStart.getX()), basegfx::fround(rStart.getY()));
 
     sal_Int32 nTableX = m_xTableShape->getPosition().X;
diff --git a/offapi/com/sun/star/chart2/XDataTable.idl b/offapi/com/sun/star/chart2/XDataTable.idl
index 8431a586cf34..3903df2f848f 100644
--- a/offapi/com/sun/star/chart2/XDataTable.idl
+++ b/offapi/com/sun/star/chart2/XDataTable.idl
@@ -17,6 +17,10 @@ module chart2
 {
 
 /** Interface for the data table of a diagram
+
+    The data table of a chart is an chart element, that shows the
+    values used to visualize the chart in a table.
+
     @since LibreOffice 7.5
  */
 interface XDataTable : ::com::sun::star::uno::XInterface
diff --git a/oox/inc/drawingml/chart/datatablecontext.hxx b/oox/inc/drawingml/chart/datatablecontext.hxx
index 01a75c6e634d..a5f6855f2ccf 100644
--- a/oox/inc/drawingml/chart/datatablecontext.hxx
+++ b/oox/inc/drawingml/chart/datatablecontext.hxx
@@ -25,8 +25,7 @@ namespace oox::drawingml::chart
 {
 struct DataTableModel;
 
-/** Handler for a data table context (c:dTable element).
- */
+/** Handler for a data table context (c:dTable element). */
 class DataTableContext final : public ContextBase<DataTableModel>
 {
 public:
diff --git a/oox/inc/drawingml/chart/datatableconverter.hxx b/oox/inc/drawingml/chart/datatableconverter.hxx
index f49d908f4aa5..9df8a30c5746 100644
--- a/oox/inc/drawingml/chart/datatableconverter.hxx
+++ b/oox/inc/drawingml/chart/datatableconverter.hxx
@@ -30,6 +30,10 @@ namespace oox::drawingml::chart
 {
 struct DataTableModel;
 
+/**
+ * Converts the data table element and properties from OOXML model to
+ * the internal chart implementation.
+ */
 class DataTableConverter final : public ConverterBase<DataTableModel>
 {
 public:
diff --git a/xmloff/source/chart/SchXMLDataTableContext.cxx b/xmloff/source/chart/SchXMLDataTableContext.cxx
index a9a26d2e1d3d..20846c5d95a8 100644
--- a/xmloff/source/chart/SchXMLDataTableContext.cxx
+++ b/xmloff/source/chart/SchXMLDataTableContext.cxx
@@ -42,6 +42,7 @@ SchXMLDataTableContext::SchXMLDataTableContext(SchXMLImportHelper& rImpHelper, S
 void SchXMLDataTableContext::startFastElement(
     sal_Int32 /*nElement*/, const uno::Reference<xml::sax::XFastAttributeList>& xAttrList)
 {
+    // Check if we have all that is needed to create the data table instance
     auto xChartDocument = mrImportHelper.GetChartDocument();
     if (!xChartDocument.is())
         return;
@@ -54,6 +55,7 @@ void SchXMLDataTableContext::startFastElement(
     if (!xDiagram.is())
         return;
 
+    // Create a new DataTable instance
     uno::Reference<lang::XMultiServiceFactory> xFactory = comphelper::getProcessServiceFactory();
     uno::Reference<chart2::XDataTable> xDataTable(
         xFactory->createInstance("com.sun.star.chart2.DataTable"), uno::UNO_QUERY);
@@ -72,7 +74,7 @@ void SchXMLDataTableContext::startFastElement(
             XMLOFF_WARN_UNKNOWN("xmloff", aIter);
     }
 
-    // set properties
+    // Set the data table properties
     uno::Reference<beans::XPropertySet> xPropertySet(xDataTable, uno::UNO_QUERY);
 
     if (!sAutoStyleName.isEmpty() && xPropertySet.is())
diff --git a/xmloff/source/chart/SchXMLDataTableContext.hxx b/xmloff/source/chart/SchXMLDataTableContext.hxx
index 716f445ed61e..fbf87fb44967 100644
--- a/xmloff/source/chart/SchXMLDataTableContext.hxx
+++ b/xmloff/source/chart/SchXMLDataTableContext.hxx
@@ -23,6 +23,7 @@
 #include <xmloff/SchXMLImportHelper.hxx>
 #include <xmloff/xmlictxt.hxx>
 
+/** Import the content of the data-table (XML_DATA_TABLE) element */
 class SchXMLDataTableContext : public SvXMLImportContext
 {
 public:
diff --git a/xmloff/source/chart/SchXMLExport.cxx b/xmloff/source/chart/SchXMLExport.cxx
index da27d1447368..e07fb6a77693 100644
--- a/xmloff/source/chart/SchXMLExport.cxx
+++ b/xmloff/source/chart/SchXMLExport.cxx
@@ -1493,7 +1493,7 @@ void SchXMLExportHelper_Impl::parseDocument( Reference< chart::XChartDocument >
         aPropertyStates.clear();
     }
 
-    // Data table
+    // Export data table element and properties
     if (xNewDiagram.is() && nCurrentODFVersion & SvtSaveOptions::ODFSVER_EXTENDED)
     {
         auto xDataTable = xNewDiagram->getDataTable();