Merge pull request #993 from jwuttke/doxy5

Added Doxygen class comments. Renamed WallclockTimer <- TimeInterval

Core/Computation/ProfileHelper.h

@@ -21,6 +21,8 @@
 #include <utility>
 #include <vector>
 
+class ProcessedSample;
+
 //! Object that can generate the material profile of a sample as a function of depth.
 //!
 //! The generated profile contains the complex SLD for SLD materials and the parameters
@@ -28,8 +30,6 @@
 //!
 //! @ingroup algorithms_internal
 
-class ProcessedSample;
-
 class BA_CORE_API_ ProfileHelper
 {
 public:

Core/Fitting/FitPrintService.h

@@ -15,7 +15,7 @@
 #ifndef FITPRINTSERVICE_H
 #define FITPRINTSERVICE_H
 
-#include "TimeInterval.h"
+#include "WallclockTimer.h"
 #include "WinDllMacros.h"
 #include <string>
 
@@ -36,8 +36,8 @@ private:
     std::string parameterString(const FitObjective& objective);
     std::string fitResultString(const FitObjective& objective);
 
-    TimeInterval m_run_time;
-    TimeInterval m_last_call_time;
+    WallclockTimer m_run_time;
+    WallclockTimer m_last_call_time;
 };
 
 #endif

Core/Instrument/RectangularDetector.h

@@ -18,7 +18,29 @@
 #include "IDetector2D.h"
 #include "IPixel.h"
 
-class RectangularPixel;
+//! A pixel in a RectangularDetector.
+
+class BA_CORE_API_ RectangularPixel : public IPixel
+{
+public:
+    RectangularPixel(kvector_t corner_pos, kvector_t width, kvector_t height);
+
+    RectangularPixel* clone() const override;
+    RectangularPixel* createZeroSizePixel(double x, double y) const override;
+    kvector_t getK(double x, double y, double wavelength) const override;
+    kvector_t getPosition(double x, double y) const;
+    double getIntegrationFactor(double x, double y) const override;
+    double getSolidAngle() const override;
+
+private:
+    kvector_t normalizeLength(const kvector_t direction, double length) const;
+    double calculateSolidAngle() const;
+    kvector_t m_corner_pos;
+    kvector_t m_width;
+    kvector_t m_height;
+    double m_solid_angle;
+    kvector_t m_normal;
+};
 
 //! A flat rectangular detector with axes and resolution function.
 //! @ingroup detector
@@ -108,26 +130,4 @@ private:
     kvector_t m_v_unit;
 };
 
-class BA_CORE_API_ RectangularPixel : public IPixel
-{
-public:
-    RectangularPixel(kvector_t corner_pos, kvector_t width, kvector_t height);
-
-    RectangularPixel* clone() const override;
-    RectangularPixel* createZeroSizePixel(double x, double y) const override;
-    kvector_t getK(double x, double y, double wavelength) const override;
-    kvector_t getPosition(double x, double y) const;
-    double getIntegrationFactor(double x, double y) const override;
-    double getSolidAngle() const override;
-
-private:
-    kvector_t normalizeLength(const kvector_t direction, double length) const;
-    double calculateSolidAngle() const;
-    kvector_t m_corner_pos;
-    kvector_t m_width;
-    kvector_t m_height;
-    double m_solid_angle;
-    kvector_t m_normal;
-};
-
 #endif // RECTANGULARDETECTOR_H

Core/Instrument/SphericalDetector.h

@@ -18,8 +18,26 @@
 #include "IDetector2D.h"
 #include "IPixel.h"
 
+//! A pixel in a SphericalDetector
+
+class BA_CORE_API_ SphericalPixel : public IPixel
+{
+public:
+    SphericalPixel(const Bin1D& alpha_bin, const Bin1D& phi_bin);
+
+    SphericalPixel* clone() const override;
+    SphericalPixel* createZeroSizePixel(double x, double y) const override;
+    kvector_t getK(double x, double y, double wavelength) const override;
+    double getIntegrationFactor(double x, double y) const override;
+    double getSolidAngle() const override;
+
+private:
+    double m_alpha, m_phi;
+    double m_dalpha, m_dphi;
+    double m_solid_angle;
+};
+
 //! A spherical detector with axes and resolution function.
-//! SphericalDetector
 //! @ingroup detector
 
 class BA_CORE_API_ SphericalDetector : public IDetector2D
@@ -61,21 +79,4 @@ protected:
     size_t getIndexOfSpecular(const Beam& beam) const override;
 };
 
-class BA_CORE_API_ SphericalPixel : public IPixel
-{
-public:
-    SphericalPixel(const Bin1D& alpha_bin, const Bin1D& phi_bin);
-
-    SphericalPixel* clone() const override;
-    SphericalPixel* createZeroSizePixel(double x, double y) const override;
-    kvector_t getK(double x, double y, double wavelength) const override;
-    double getIntegrationFactor(double x, double y) const override;
-    double getSolidAngle() const override;
-
-private:
-    double m_alpha, m_phi;
-    double m_dalpha, m_dphi;
-    double m_solid_angle;
-};
-
 #endif // SPHERICALDETECTOR_H

Core/Parametrization/ParameterDistribution.h

@@ -23,6 +23,8 @@
 
 class IDistribution1D;
 
+//! A parametric distribution function, for use with any model parameter.
+
 class BA_CORE_API_ ParameterDistribution : public IParameterized
 {
 public:

Core/Scattering/Rotations.h

@@ -46,6 +46,8 @@ BA_CORE_API_ IRotation* createProduct(const IRotation& left, const IRotation& ri
 
 bool IsZRotation(const IRotation& rot);
 
+//! The identity rotation, which leaves everything in place.
+
 class BA_CORE_API_ IdentityRotation : public IRotation
 {
 public:
@@ -61,6 +63,8 @@ public:
     bool isIdentity() const { return true; }
 };
 
+//! A rotation about the x axis.
+
 class BA_CORE_API_ RotationX : public IRotation
 {
 public:
@@ -79,6 +83,8 @@ protected:
     double m_angle;
 };
 
+//! A rotation about the y axis.
+
 class BA_CORE_API_ RotationY : public IRotation
 {
 public:
@@ -97,6 +103,8 @@ protected:
     double m_angle;
 };
 
+//! A rotation about the z axis.
+
 class BA_CORE_API_ RotationZ : public IRotation
 {
 public:
@@ -115,6 +123,8 @@ protected:
     double m_angle;
 };
 
+//! A sequence of rotations about the z-x'-z'' axes.
+
 class BA_CORE_API_ RotationEuler : public IRotation
 {
 public:

Fit/Kernel/Kernel.cpp

@@ -46,15 +46,15 @@ MinimizerResult Kernel::minimize(fcn_scalar_t fcn, const Parameters& parameters)
 {
     setParameters(parameters);
 
-    m_time_interval.start();
+    m_timer.start();
     if (m_minimizer->requiresResiduals())
         throw std::runtime_error(
             "Error in Kernel::minimize: the chosen minimizer requires residuals computation. "
             "Please use FitObjective::evaluate_residuals with this minimizer.");
     auto result = m_minimizer->minimize_scalar(fcn, parameters);
-    m_time_interval.stop();
+    m_timer.stop();
 
-    result.setDuration(m_time_interval.runTime());
+    result.setDuration(m_timer.runTime());
     return result;
 }
 
@@ -62,11 +62,11 @@ MinimizerResult Kernel::minimize(fcn_residual_t fcn, const Parameters& parameter
 {
     setParameters(parameters);
 
-    m_time_interval.start();
+    m_timer.start();
     auto result = m_minimizer->minimize_residual(fcn, parameters);
-    m_time_interval.stop();
+    m_timer.stop();
 
-    result.setDuration(m_time_interval.runTime());
+    result.setDuration(m_timer.runTime());
     return result;
 }
 

Fit/Kernel/Kernel.h

@@ -18,7 +18,7 @@
 #include "KernelTypes.h"
 #include "MinimizerResult.h"
 #include "Parameters.h"
-#include "TimeInterval.h"
+#include "WallclockTimer.h"
 #include "WinDllMacros.h"
 #include <functional>
 #include <memory>
@@ -51,7 +51,7 @@ private:
 
     Parameters m_parameters;
     std::unique_ptr<IMinimizer> m_minimizer;
-    TimeInterval m_time_interval;
+    WallclockTimer m_timer;
 };
 
 } // namespace Fit

Fit/Tools/TimeInterval.cpp → Fit/Tools/WallclockTimer.cpp

@@ -2,8 +2,8 @@
 //
 //  BornAgain: simulate and fit scattering at grazing incidence
 //
-//! @file      Fit/Tools/TimeInterval.cpp
-//! @brief     Implements TimeInterval class.
+//! @file      Fit/Tools/WallclockTimer.cpp
+//! @brief     Implements WallclockTimer class.
 //!
 //! @homepage  http://www.bornagainproject.org
 //! @license   GNU General Public License v3 or higher (see COPYING)
@@ -12,43 +12,43 @@
 //
 // ************************************************************************** //
 
-#include "TimeInterval.h"
+#include "WallclockTimer.h"
 #include <chrono>
 
 using clock_used = std::chrono::high_resolution_clock;
-using duration_unit = std::chrono::milliseconds;
+using duration_unit = std::chrono::seconds;
 
-class TimeIntervalImp
+//! Internal state of a WallclockTimer object.
+
+struct WallclockTimerState
 {
-public:
     std::chrono::time_point<clock_used> m_start_time;
     std::chrono::time_point<clock_used> m_end_time;
-    bool m_is_running;
-    TimeIntervalImp() : m_is_running(false) {}
+    bool m_is_running {false};
 };
 
-TimeInterval::TimeInterval() : m_imp(new TimeIntervalImp) {}
-
-TimeInterval::~TimeInterval() = default;
+WallclockTimer::WallclockTimer() : m_state(new WallclockTimerState) {}
+WallclockTimer::~WallclockTimer() = default;
 
-void TimeInterval::start()
+void WallclockTimer::start()
 {
-    m_imp->m_is_running = true;
-    m_imp->m_start_time = clock_used::now();
+    m_state->m_is_running = true;
+    m_state->m_start_time = clock_used::now();
 }
 
-void TimeInterval::stop()
+void WallclockTimer::stop()
 {
-    m_imp->m_is_running = false;
-    m_imp->m_end_time = clock_used::now();
+    m_state->m_is_running = false;
+    m_state->m_end_time = clock_used::now();
 }
 
-double TimeInterval::runTime() const
+double WallclockTimer::runTime() const
 {
     duration_unit diff =
-        m_imp->m_is_running
-            ? std::chrono::duration_cast<duration_unit>(clock_used::now() - m_imp->m_start_time)
-            : std::chrono::duration_cast<duration_unit>(m_imp->m_end_time - m_imp->m_start_time);
+        m_state->m_is_running
+            ? std::chrono::duration_cast<duration_unit>(clock_used::now() - m_state->m_start_time)
+            : std::chrono::duration_cast<duration_unit>(
+                m_state->m_end_time - m_state->m_start_time);
 
-    return diff.count() / 1000.;
+    return diff.count();
 }

Fit/Tools/TimeInterval.h → Fit/Tools/WallclockTimer.h

@@ -2,8 +2,8 @@
 //
 //  BornAgain: simulate and fit scattering at grazing incidence
 //
-//! @file      Fit/Tools/TimeInterval.h
-//! @brief     Defines TimeInterval class.
+//! @file      Fit/Tools/WallclockTimer.h
+//! @brief     Defines WallclockTimer class.
 //!
 //! @homepage  http://www.bornagainproject.org
 //! @license   GNU General Public License v3 or higher (see COPYING)
@@ -18,22 +18,24 @@
 #include "WinDllMacros.h"
 #include <memory>
 
-class TimeIntervalImp;
+struct WallclockTimerState;
 
-class BA_CORE_API_ TimeInterval
+//! A timer for measuring real (wall-clock) time spent between 'start' and 'stop' commands.
+
+class BA_CORE_API_ WallclockTimer
 {
 public:
-    TimeInterval();
-    ~TimeInterval();
+    WallclockTimer();
+    ~WallclockTimer();
 
     void start();
     void stop();
 
-    //! returns run time in sec.msec
+    //! returns run time in sec.
     double runTime() const;
 
 private:
-    std::unique_ptr<TimeIntervalImp> m_imp;
+    std::unique_ptr<WallclockTimerState> m_state;
 };
 
 #endif // TIMEINTERVAL_H

GUI/coregui/Views/CommonWidgets/UpdateTimer.cpp

@@ -31,7 +31,7 @@ void UpdateTimer::reset()
     m_is_busy = false;
 }
 
-void UpdateTimer::setTimeInterval(int timerInterval)
+void UpdateTimer::setWallclockTimer(int timerInterval)
 {
     m_timer_interval = timerInterval;
 }

GUI/coregui/Views/CommonWidgets/UpdateTimer.h

@@ -33,7 +33,7 @@ public:
 
     void reset();
 
-    void setTimeInterval(int timerInterval);
+    void setWallclockTimer(int timerInterval);
 
 signals:
     void timeToUpdate();

GUI/coregui/mainwindow/AutosaveController.cpp

@@ -51,7 +51,7 @@ void AutosaveController::setDocument(ProjectDocument* document)
 void AutosaveController::setAutosaveTime(int timerInterval)
 {
     m_timer->reset();
-    m_timer->setTimeInterval(timerInterval);
+    m_timer->setWallclockTimer(timerInterval);
 }
 
 //! Returns the name of autosave directory.

Tests/Functional/TestMachinery/Benchmark.h

@@ -16,7 +16,7 @@
 #define BENCHMARK_H
 
 #include "OrderedMap.h"
-#include "TimeInterval.h"
+#include "WallclockTimer.h"
 #include "WinDllMacros.h"
 #include <functional>
 #include <map>
@@ -27,16 +27,16 @@ class BA_CORE_API_ Duration
 public:
     Duration() : m_totalTime(0) {}
 
-    void start() { m_time_interval.start(); }
+    void start() { m_timer.start(); }
     void stop()
     {
-        m_time_interval.stop();
-        m_totalTime += m_time_interval.runTime();
+        m_timer.stop();
+        m_totalTime += m_timer.runTime();
     }
     double runTime() const { return m_totalTime; }
 
 private:
-    TimeInterval m_time_interval;
+    WallclockTimer m_timer;
     double m_totalTime;
 };