From 1f7af858cdecb9c5c2db0e295467b7a726b948c7 Mon Sep 17 00:00:00 2001
From: Federico Montesino Pouzols <federico.montesino-pouzols@stfc.ac.uk>
Date: Wed, 7 Oct 2015 12:20:08 +0100
Subject: [PATCH] doxygen tags and more code documentation, re #13140

---
 .../Tomography/IImageCoRView.h                | 10 ++-----
 .../Tomography/ImageCoRViewQtWidget.h         |  2 ++
 .../src/Tomography/ImageCoRViewQtWidget.cpp   | 29 ++++++++++++++++++-
 3 files changed, 33 insertions(+), 8 deletions(-)

diff --git a/Code/Mantid/MantidQt/CustomInterfaces/inc/MantidQtCustomInterfaces/Tomography/IImageCoRView.h b/Code/Mantid/MantidQt/CustomInterfaces/inc/MantidQtCustomInterfaces/Tomography/IImageCoRView.h
index 81f64bdb6b8..68c11500165 100644
--- a/Code/Mantid/MantidQt/CustomInterfaces/inc/MantidQtCustomInterfaces/Tomography/IImageCoRView.h
+++ b/Code/Mantid/MantidQt/CustomInterfaces/inc/MantidQtCustomInterfaces/Tomography/IImageCoRView.h
@@ -59,8 +59,8 @@ public:
    * are updated (including spin boxes, image, slider through the
    * image stack, etc.
    *
-   * @param tools identifiers of the tools that can or could be run.
-   * Order matters
+   * @param params all user-modifyable parameters (coordinates for the
+   * CoR, ROI and area for normalization).
    *
    */
   virtual void setParams(ImageStackPreParams &params) = 0;
@@ -84,7 +84,7 @@ public:
   /**
    * Update to a new state (for example select CoR).
    *
-   * @param new state we're transitioning into.
+   * @param state new state we're transitioning into.
    */
   virtual void changeSelectionState(const SelectionState& state) = 0;
 
@@ -110,10 +110,6 @@ public:
    * @param ws Workspace group where every workspace is a FITS or
    * similar image that has been loaded with LoadFITS or similar
    * algorithm.
-   *
-   * @param the (valid) path for this stack, from which it the
-   * workspace group was loaded, in whatever directory layout is being
-   * used (unknown to this view).
    */
   virtual void showStack(Mantid::API::WorkspaceGroup_sptr &ws) = 0;
 
diff --git a/Code/Mantid/MantidQt/CustomInterfaces/inc/MantidQtCustomInterfaces/Tomography/ImageCoRViewQtWidget.h b/Code/Mantid/MantidQt/CustomInterfaces/inc/MantidQtCustomInterfaces/Tomography/ImageCoRViewQtWidget.h
index 037de649329..bfc33db8f93 100644
--- a/Code/Mantid/MantidQt/CustomInterfaces/inc/MantidQtCustomInterfaces/Tomography/ImageCoRViewQtWidget.h
+++ b/Code/Mantid/MantidQt/CustomInterfaces/inc/MantidQtCustomInterfaces/Tomography/ImageCoRViewQtWidget.h
@@ -140,12 +140,14 @@ private:
   /// initialize values to defaults and set max/min for the spin boxes
   void initParamWidgets(size_t maxWidth, size_t maxHeight);
 
+  /// Set coordinates in the widgets from a params object
   void setParamWidgets(ImageStackPreParams &params);
 
   // shows the image in a widget
   void showProjectionImage(const Mantid::API::WorkspaceGroup_sptr &wsg,
                            size_t idx);
 
+  /// repaint the image with new positions of points and rectangles
   void refreshROIetAl();
   void refreshCoR();
   void refreshROI();
diff --git a/Code/Mantid/MantidQt/CustomInterfaces/src/Tomography/ImageCoRViewQtWidget.cpp b/Code/Mantid/MantidQt/CustomInterfaces/src/Tomography/ImageCoRViewQtWidget.cpp
index 2dddb66e51f..9d28caed00b 100644
--- a/Code/Mantid/MantidQt/CustomInterfaces/src/Tomography/ImageCoRViewQtWidget.cpp
+++ b/Code/Mantid/MantidQt/CustomInterfaces/src/Tomography/ImageCoRViewQtWidget.cpp
@@ -115,6 +115,21 @@ void ImageCoRViewQtWidget::setupConnections() {
           SLOT(valueUpdatedNormArea(int)));
 }
 
+/**
+ * Qt events filter for the mouse click and click&drag events that are
+ * used to select points and rectangles. Part of the logic of the
+ * selection is handled here. The test on the presenter can only test
+ * the begin and end of the selection. For full testability (including
+ * the mouse interaction), this method should be implemented fully in
+ * terms of notifications to the presenter. This would require a bunch
+ * of new notifications in IImageCoRPresenter, and making at least all
+ * the mouseUpdateCoR, mouseUpdateROICorners12, mouseXXX methods
+ * public in this view interface. This can be considered at a later
+ * stage.
+ *
+ * @param obj object concerned by the event
+ * @param event event received (mouse click, release, move, etc.)
+ **/
 bool ImageCoRViewQtWidget::eventFilter(QObject *obj, QEvent *event) {
   // quick ignore
   if (IImageCoRView::SelectNone == m_selectionState)
@@ -174,6 +189,10 @@ void ImageCoRViewQtWidget::valueUpdatedNormArea(int) {
   refreshROIetAl();
 }
 
+/**
+ * Parameter values from spin box widgets => coordinate parameters
+ * data member
+ */
 void ImageCoRViewQtWidget::grabCoRFromWidgets() {
   m_params.cor = Mantid::Kernel::V2D(m_ui.spinBox_cor_x->value(),
                                      m_ui.spinBox_cor_y->value());
@@ -195,6 +214,14 @@ void ImageCoRViewQtWidget::grabNormAreaFromWidgets() {
                                          m_ui.spinBox_norm_bottom_y->value()));
 }
 
+/**
+ * Parameter values from mouse position (at a relevant event like
+ * first click, or last release) => spin box widgets, AND coordinate
+ * parameters data member. This grabs the Center of Rotation (CoR)
+ *
+ * @param x position on x axis (local to the image)
+ * @param y position on y axis (local to the image)
+ */
 void ImageCoRViewQtWidget::grabCoRFromMousePoint(int x, int y) {
   m_params.cor = Mantid::Kernel::V2D(x, y);
   m_ui.spinBox_cor_x->setValue(x);
@@ -231,7 +258,7 @@ void ImageCoRViewQtWidget::grabNormAreaCorner2FromMousePoint(int x, int y) {
  * usual in Qt widgets. Top-left is (0,0).
  *
  * @param x position on x axis (local to the image)
- * @param x position on y axis (local to the image)
+ * @param y position on y axis (local to the image)
  */
 void ImageCoRViewQtWidget::mouseUpdateCoR(int x, int y) {
   grabCoRFromMousePoint(x, y);
-- 
GitLab