From 7ae4e85ffe27753f87c6cf2bd8b7617ee39f8996 Mon Sep 17 00:00:00 2001
From: Johannes Lorenz <j.git@lorenz-ho.me>
Date: Mon, 22 Apr 2019 11:05:59 +0200
Subject: [PATCH] Document graph widget

---
 include/Graph.h           | 38 ++++++++++++++++++++++++++++++++------
 src/gui/widgets/Graph.cpp |  5 +++--
 2 files changed, 35 insertions(+), 8 deletions(-)

diff --git a/include/Graph.h b/include/Graph.h
index 4827bda40..1bee05c41 100644
--- a/include/Graph.h
+++ b/include/Graph.h
@@ -44,13 +44,18 @@ class LMMS_EXPORT Graph : public QWidget, public ModelView
 public:
 	enum graphStyle
 	{
-		NearestStyle,
-		LinearStyle,
-		LinearNonCyclicStyle,
-		BarStyle,
+		NearestStyle, //!< draw as stairs
+		LinearStyle, //!< connect each 2 samples with a line, with wrapping
+		LinearNonCyclicStyle, //!< LinearStyle without wrapping
+		BarStyle, //!< draw thick bars
 		NumGraphStyles
 	};
 
+	/**
+	 * @brief Constructor
+	 * @param _width Pixel width of widget
+	 * @param _height Pixel height of widget
+	 */
 	Graph( QWidget * _parent, graphStyle _style = Graph::LinearStyle,
 		int _width = 132,
 		int _height = 104
@@ -111,10 +116,24 @@ private:
 } ;
 
 
+/**
+	@brief 2 dimensional function plot
+
+	Function plot graph with discrete x scale and continous y scale
+	This makes it possible to display "#x" samples
+*/
 class LMMS_EXPORT graphModel : public Model
 {
 	Q_OBJECT
 public:
+	/**
+	 * @brief Constructor
+	 * @param _min Minimum y value to display
+	 * @param _max Maximum y value to display
+	 * @param _size Number of samples (e.g. x value)
+	 * @param _step Step size on y axis where values snap to, or 0.0f
+	 *   for "no snapping"
+	 */
 	graphModel( float _min,
 			float _max,
 			int _size,
@@ -146,14 +165,21 @@ public:
 		return( m_samples.data() );
 	}
 
-	void convolve(const float *convolution, const int convolutionLength, const int centerOffset);
+	//! Make cyclic convolution
+	//! @param convolution Samples to convolve with
+	//! @param convolutionLength Number of samples to take for each sum
+	//! @param centerOffset Offset for resulting values
+	void convolve(const float *convolution,
+		const int convolutionLength, const int centerOffset);
 
 public slots:
+	//! Set range of y values
 	void setRange( float _min, float _max );
 
 	void setLength( int _size );
-
+	//! Update one sample
 	void setSampleAt( int x, float val );
+	//! Update samples array
 	void setSamples( const float * _value );
 
 	void setWaveToSine();
diff --git a/src/gui/widgets/Graph.cpp b/src/gui/widgets/Graph.cpp
index f93ed523c..4710089dd 100644
--- a/src/gui/widgets/Graph.cpp
+++ b/src/gui/widgets/Graph.cpp
@@ -635,13 +635,14 @@ void graphModel::smoothNonCyclic()
 	emit samplesChanged(0, length()-1);
 }
 
-//makes a cyclic convolution.
-void graphModel::convolve(const float *convolution, const int convolutionLength, const int centerOffset)
+void graphModel::convolve(const float *convolution,
+	const int convolutionLength, const int centerOffset)
 {
 	// store values in temporary array
 	QVector<float> temp = m_samples;
 	const int graphLength = length();
 	float sum;
+	// make a cyclic convolution
 	for ( int i = 0; i <  graphLength; i++ )
 	{
 		sum = 0;