Resolve all Doxygen warnings & docs cleanup

doc/CMakeLists.txt

@@ -1,14 +1,7 @@
 FIND_PACKAGE(Doxygen)
 
 if(DOXYGEN_FOUND)
-	set(INPUTDIRS 
-		"\"${CMAKE_CURRENT_SOURCE_DIR}../src/core\"
-		\"${CMAKE_CURRENT_SOURCE_DIR}../src/gui\"
-		\"${CMAKE_CURRENT_SOURCE_DIR}../src/tracks\"
-		\"${CMAKE_CURRENT_SOURCE_DIR}../include\"
-		\"${CMAKE_CURRENT_SOURCE_DIR}../plugins\"")
 	CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile @ONLY)
-
 	ADD_CUSTOM_TARGET(doc
 		COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
 		WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
@@ -17,4 +10,3 @@ if(DOXYGEN_FOUND)
 endif(DOXYGEN_FOUND)
 
 ADD_SUBDIRECTORY(bash-completion)
-

include/AudioBuffer.h

@@ -51,7 +51,7 @@ namespace lmms
  *       efficiently using the data from silence tracking
  * - Can organize channels into arbitrary groups. For example, you could have 6 total channels divided into 2 groups
  *       where the 1st group contains 2 channels (stereo) and the 2nd contains 4 channels (quadraphonic).
- * - Extensive unit testing - @ref AudioBufferTest.cpp
+ * - Extensive unit testing - See AudioBufferTest.cpp
  *
  * Audio data layout explanation:
  * - All planar audio data for all channels in an AudioBuffer is sourced from the same large contiguous

include/AudioBusHandle.h

@@ -44,9 +44,9 @@ class BoolModel;
 	@brief Job between @ref PlayHandle and @ref MixerChannel
 
 	A @ref ThreadableJob class located at the exit point of each @ref PlayHandle into a @ref MixerChannel
-	(or into an audio device, in case of @ref AudioJack, but this is not supported in AudioBusHandle yet).
+	(or into an audio device, in case of AudioJack, but this is not supported in AudioBusHandle yet).
 	It contains an optional @ref EffectChain which is e.g. visualized in the
-	@ref InstrumentTrackWindow or @ref SampleTrackWindow.
+	@ref gui::InstrumentTrackWindow or @ref gui::SampleTrackWindow.
 	For processing, it adds all input play handles into an internal buffer,
 	processes the @ref EffectChain (if existing) on that buffer
 	and finally merges the buffer into its @ref MixerChannel.

include/AudioEngine.h

@@ -274,7 +274,7 @@ class LMMS_EXPORT AudioEngine : public QObject
 	/**
 	 * @brief Renders an audio buffer into @a dst.
 	 *
-	 * Renders @ref renderNextAudioPeriod() "audio periods" into @a dst. If @a dst is not a multiple of the period
+	 * Renders @ref renderNextPeriod() "audio periods" into @a dst. If @a dst is not a multiple of the period
 	 * size, the remaining frames are partially rendered (an extra period may be rendered in such cases, which can
 	 * degrade performance).
 	 *

include/AutomatableModel.h

@@ -255,19 +255,22 @@ class LMMS_EXPORT AutomatableModel : public Model, public JournallingObject
 	//! @return number of other models linked to this
 	size_t countLinks() const;
 
-	/**
-	 * @brief Saves settings (value, automation links and controller connections) of AutomatableModel into
-	 *  specified DOM element using <name> as attribute/node name
-	 * @param doc TODO
-	 * @param element Where this option shall be saved.
-	 *  Depending on the model, this can be done in an attribute or in a subnode.
-	 * @param name Name to store this model as.
-	 */
-	virtual void saveSettings( QDomDocument& doc, QDomElement& element, const QString& name );
-
-	/*! \brief Loads settings (value, automation links and controller connections) of AutomatableModel from
-				specified DOM element using <name> as attribute/node name */
-	virtual void loadSettings( const QDomElement& element, const QString& name );
+	//! @brief Saves settings of AutomatableModel into a DOM element
+	//!
+	//! Saves settings (value, automation links and controller connections) of AutomatableModel into DOM element
+	//! @p element using @p name as attribute/node name.
+	//! 
+	//! @param doc TODO
+	//! @param element Where this option shall be saved. Depending on the model, this can be done in an attribute or in a
+	//! subnode.
+	//! @param name Name to store this model as.
+	virtual void saveSettings(QDomDocument& doc, QDomElement& element, const QString& name);
+
+	//! @brief Loads settings of AutomatableModel from a DOM element
+	//!
+	//! Loads settings (value, automation links and controller connections) of AutomatableModel from DOM element
+	//! @p element using @p name as attribute/node name.
+	virtual void loadSettings(const QDomElement& element, const QString& name);
 
 	QString nodeName() const override
 	{
@@ -374,16 +377,18 @@ public slots:
 	//! @return the model whose `m_nextLink` is `this`,
 	//! or `this` if there are no linked models
 	AutomatableModel* getLastLinkedModel() const;
+
 	//! @return true if the `model` is in the linked list
 	bool isLinkedToModel(AutomatableModel* model) const;
 
-	//! @brief Scales @value from linear to logarithmic.
-	//! Value should be within [0,1]
-	template<class T> T logToLinearScale( T value ) const;
-
-	//! rounds @a value to @a where if it is close to it
-	//! @param value will be modified to rounded value
-	template<class T> void roundAt( T &value, const T &where ) const;
+	//! @brief Scales @p value from linear to logarithmic.
+	//! @param value A linear value. Should be within [0,1].
+	template<class T> T logToLinearScale(T value) const;
+
+	//! @brief Rounds @p value to @p where if it is close to it
+	//! @param[out] value Will be modified to rounded value
+	//! @param[in] where The number to round @p value to, if it is near enough
+	template<class T> void roundAt(T &value, const T &where) const;
 
 
 	ScaleType m_scaleType; //!< scale type, linear by default

include/AutomationClip.h

@@ -88,40 +88,74 @@ class LMMS_EXPORT AutomationClip : public Clip
 	TimePos timeMapLength() const;
 	void updateLength() override;
 
+	//! @brief Puts an automation node on the timeMap with the given value.
+	//!
+	//! The inValue and outValue of the created node will be the same.
+	//!
+	//! @param time Time to add the node to
+	//! @param value inValue and outValue of the node
+	//! @param quantPos True to quantize the position (defaults to true)
+	//! @param ignoreSurroundingPoints True to ignore unquantized surrounding nodes (defaults to true)
+	//! @return TimePos of the recently added automation node
 	TimePos putValue(
-		const TimePos & time,
+		const TimePos& time,
 		const float value,
 		const bool quantPos = true,
 		const bool ignoreSurroundingPoints = true
 	);
 
+	//! @brief Puts an automation node on the timeMap with the given inValue and outValue.
+	//! @param time Time to add the node to
+	//! @param inValue inValue of the node
+	//! @param outValue outValue of the node
+	//! @param quantPos True to quantize the position (defaults to true)
+	//! @param ignoreSurroundingPoints True to ignore unquantized surrounding nodes (defaults to true)
+	//! @return TimePos of the recently added automation node
 	TimePos putValues(
-		const TimePos & time,
+		const TimePos& time,
 		const float inValue,
 		const float outValue,
 		const bool quantPos = true,
 		const bool ignoreSurroundingPoints = true
 	);
 
 	void removeNode(const TimePos & time);
+
+	//! @brief Removes all automation nodes between the given ticks
+	//! @param tick0 first tick of the range
+	//! @param tick1 second tick of the range
 	void removeNodes(const int tick0, const int tick1);
 
+	//! @brief Resets the outValues of all automation nodes between the given ticks
+	//! @param tick0 first tick of the range
+	//! @param tick1 second tick of the range
 	void resetNodes(const int tick0, const int tick1);
 
-	/**
-	 * @brief Resets the tangents from the nodes between the given ticks
-	 * @param Int first tick of the range
-	 * @param Int second tick of the range
-	 */
+	//! @brief Resets the tangents from the nodes between the given ticks
+	//! @param tick0 first tick of the range
+	//! @param tick1 second tick of the range
 	void resetTangents(const int tick0, const int tick1);
 
 	void recordValue(TimePos time, float value);
 
-	TimePos setDragValue( const TimePos & time,
-				const float value,
-				const bool quantPos = true,
-				const bool controlKey = false );
+	//! @brief Set the position of the point that is being dragged.
+	//!
+	//! Calling this function will also automatically set m_dragging to true.
+	//! When applyDragValue() is called, m_dragging is set back to false.
+	//!
+	//! @param time TimePos of the node being dragged
+	//! @param value with the value to assign to the point being dragged
+	//! @param quantPos True to snip x position
+	//! @param controlKey True to ignore unquantized surrounding nodes
+	//! @return TimePos with current time of the dragged value
+	TimePos setDragValue(
+		const TimePos& time,
+		const float value,
+		const bool quantPos = true,
+		const bool controlKey = false
+	);
 
+	//! @brief After the point is dragged, this function is called to apply the change.
 	void applyDragValue();
 
 
@@ -182,7 +216,11 @@ class LMMS_EXPORT AutomationClip : public Clip
 
 
 	static bool isAutomated( const AutomatableModel * _m );
+
+	//! @brief Returns a list of all the automation clips that are connected to a specific model
+	//! @param _m The model we want to look for
 	static std::vector<AutomationClip*> clipsForModel(const AutomatableModel* _m);
+
 	static AutomationClip * globalAutomationClip( AutomatableModel * _m );
 	static void resolveAllIDs();
 

include/AutomationEditor.h

@@ -125,13 +125,21 @@ public slots:
 	float yCoordOfLevel( float level );
 	inline void drawLevelTick(QPainter & p, int tick, float value);
 
+	//! @brief Returns the automation node at a given mouse position, if any.
+	//
+	//! Given a mouse coordinate, returns a timeMap::iterator that points to the first node inside a square of side "r"
+	//! pixels from those coordinates.
+	//!
+	//! @param x X coordinate
+	//! @param y Y coordinate
+	//! @param outValue True to check if the outValue of the node was clicked instead (defaults to false)
+	//! @param r R distance in pixels
+	//! @return `timeMap::iterator` with the clicked node, or `timeMap.end()` if none was clicked.
 	timeMap::iterator getNodeAt(int x, int y, bool outValue = false, int r = 5);
-	/**
-	 * @brief Given a mouse X coordinate, returns a timeMap::iterator that points to
-	 *        the closest node.
-	 * @param Int X coordinate
-	 * @return timeMap::iterator with the closest node or timeMap.end() if there are no nodes.
-	 */
+
+	//! @brief Given a mouse X coordinate, returns a `timeMap::iterator` that points to the closest node.
+	//! @param x The X coordinate
+	//! @return `timeMap::iterator` with the closest node or `timeMap.end()` if there are no nodes.
 	timeMap::iterator getClosestNode(int x);
 
 	void drawLine( int x0, float y0, int x1, float y1 );
@@ -148,12 +156,12 @@ protected slots:
 	void setEditMode(int mode);
 
 	void setProgressionType(AutomationClip::ProgressionType type);
-	/**
-	 * @brief This method handles the AutomationEditorWindow event of changing
-	 * progression types. After that, it calls updateEditTanButton so the edit
-	 * tangents button is updated accordingly
-	 * @param Int New progression type
-	 */
+
+	//! @brief Handles the AutomationEditorWindow event of changing progression types.
+	//!
+	//! After that, it calls updateEditTanButton so the edit tangents button is updated accordingly
+	//!
+	//! @param type New progression type
 	void setProgressionType(int type);
 	void setTension();
 
@@ -162,7 +170,7 @@ protected slots:
 	void zoomingXChanged();
 	void zoomingYChanged();
 
-	/// Updates the clip's quantization using the current user selected value.
+	//! @brief Updates the clip's quantization using the current user selected value.
 	void setQuantization();
 
 	void resetGhostNotes()
@@ -196,9 +204,9 @@ protected slots:
 
 	static const int VALUES_WIDTH = 64;
 
-	static const int NOTE_HEIGHT = 10; // height of individual notes
-	static const int NOTE_MARGIN = 40; // total border margin for notes
-	static const int MIN_NOTE_RANGE = 20; // min number of keys for fixed size
+	static const int NOTE_HEIGHT = 10; //!< Height of individual notes
+	static const int NOTE_MARGIN = 40; //!< Total border margin for notes
+	static const int MIN_NOTE_RANGE = 20; //!< Min number of keys for fixed size
 	static const int SAMPLE_MARGIN = 40;
 	static constexpr int MAX_SAMPLE_HEIGHT = 400; // constexpr for use in min
 
@@ -255,12 +263,13 @@ protected slots:
 	int m_y_delta;
 	bool m_y_auto;
 
-	// Time position (key) of automation node whose outValue is being dragged
+	//! Time position (key) of automation node whose outValue is being dragged
 	int m_draggedOutValueKey;
 
-	// The tick from the node whose tangent is being dragged
+	//! The tick from the node whose tangent is being dragged
 	int m_draggedTangentTick;
-	// Whether the tangent being dragged is the InTangent or OutTangent
+
+	//! Whether the tangent being dragged is the InTangent or OutTangent
 	bool m_draggedOutTangent;
 
 	EditMode m_editMode;
@@ -344,12 +353,9 @@ protected slots:
 private slots:
 	void updateWindowTitle();
 	void setProgressionType(int progType);
-	/**
-	 * @brief The Edit Tangent edit mode should only be available for
-	 * Cubic Hermite progressions, so this method is responsible for disabling it
-	 * for other edit modes and reenabling it when it changes back to the Edit Tangent
-	 * mode.
-	 */
+
+	//! The Edit Tangent edit mode should only be available for Cubic Hermite progressions, so this method is responsible
+	//! for disabling it for other edit modes and reenabling it when it changes back to the Edit Tangent mode.
 	void updateEditTanButton();
 
 private: