Mercurial > ldforge / changeset

--- a/src/MessageLog.cc	Wed Mar 05 17:12:22 2014 +0200
+++ b/src/MessageLog.cc	Wed Mar 05 17:29:27 2014 +0200
@@ -44,9 +44,6 @@
 			expiry (QDateTime::currentDateTime().addSecs (g_expiry)) {}
 
 // =============================================================================
-// Check this line's expiry and update alpha accordingly. Returns true if the
-// line is to still stick around, false if it expired. 'changed' is updated to
-// whether the line has somehow changed since the last update.
 //
 bool MessageManager::Line::update (bool& changed)
 {

--- a/src/MessageLog.h	Wed Mar 05 17:12:22 2014 +0200
+++ b/src/MessageLog.h	Wed Mar 05 17:29:27 2014 +0200
@@ -25,27 +25,38 @@
 class GLRenderer;
 class QTimer;
 
-/* The message manager is an object which keeps track of messages that appear
- * on the renderer's screen. Each line is contained in a separate object which
- * contains the text, expiry time and alpha. The message manager is doubly
- * linked to its corresponding renderer.
- *
- * Message manager calls its tick() function regularly to update the messages,
- * where each line's expiry is checked for. Lines begin to fade out when nearing
- * their expiry. If the message manager's lines change, the renderer undergoes
- * repainting.
- */
+//!
+//! @brief Manages the list of messages at the top-left of the renderer.
+//!
+//! The message manager is an object which keeps track of messages that appear
+//! on the renderer's screen. Each line is contained in a separate object which
+//! contains the text, expiry time and alpha. The message manager is doubly
+//! linked to its corresponding renderer.
+//!
+//! Message manager calls its @c tick() function regularly to update the messages,
+//! where each line's expiry is checked for. Lines begin to fade out when nearing
+//! their expiry. If the message manager's lines change, the renderer undergoes
+//! repainting.
+//!
 class MessageManager : public QObject
 {
 	Q_OBJECT
 	PROPERTY (public, GLRenderer*, renderer, setRenderer, STOCK_WRITE)
 
 	public:
-		// Single line of the message log.
+		//! @class MessageManager::Line
+		//! A single line of the message log.
 		class Line
 		{
 			public:
+				//! Constructs a line with the given @c text
 				Line (QString text);
+
+				//! Check this line's expiry and update alpha accordingly.
+				//! @c changed is updated to whether the line has somehow
+				//! changed since the last update.
+				//! @returns true if the line is to still stick around, false
+				//! @returns if it expired.
 				bool update (bool& changed);
 
 				QString text;
@@ -53,14 +64,21 @@
 				QDateTime expiry;
 		};
 
-		explicit MessageManager (QObject* parent = 0);
+		//! Constructs the message manager.
+		explicit MessageManager (QObject* parent = null);
+
+		//! Adds a line with the given @c text to the message manager.
 		void addLine (QString line);
+
+		//! @returns all active lines in the message manager.
 		const QList<Line>& getLines() const;
 
 	private:
-		QList<Line> m_lines;
-		QTimer* m_ticker;
+		QList<Line>	m_lines;
+		QTimer*		m_ticker;
 
 	private slots:
+		//! Ticks the manager. This is called by the timer to update
+		//! the messages.
 		void tick();
 };

--- a/src/misc/RingFinder.cc	Wed Mar 05 17:12:22 2014 +0200
+++ b/src/misc/RingFinder.cc	Wed Mar 05 17:29:27 2014 +0200
@@ -22,15 +22,6 @@
 RingFinder g_RingFinder;
 
 // =============================================================================
-// This is the main algorithm of the ring finder. It tries to use math to find
-// the one ring between r0 and r1. If it fails (the ring number is non-integral),
-// it finds an intermediate radius (ceil of the ring number times scale) and
-// splits the radius at this point, calling this function again to try find the
-// rings between r0 - r and r - r1.
-//
-// This does not always yield into usable results. If at some point r == r0 or
-// r == r1, there is no hope of finding the rings, at least with this algorithm,
-// as it would fall into an infinite recursion.
 //
 bool RingFinder::findRingsRecursor (double r0, double r1, Solution& currentSolution)
 {

--- a/src/misc/RingFinder.h	Wed Mar 05 17:12:22 2014 +0200
+++ b/src/misc/RingFinder.h	Wed Mar 05 17:29:27 2014 +0200
@@ -20,65 +20,108 @@
 
 #include "../Main.h"
 
-// =============================================================================
-// RingFinder
-//
-// Provides an algorithm for finding a solution of rings between radii r0 and r1.
-// =============================================================================
+//!
+//! @brief Provides an algorithm for finding solutions of rings between given radii.
+//!
+//! The RingFinder is a class which implements a ring finding algorithm. It is passed
+//! two radii and it tries to find solutions of rings that would fill the given space.
+//!
+//! @note It is not fool-proof and does not always yield a solution, never assume
+//! @note that one is a available as none is guaranteed.
+//!
 class RingFinder
 {
 	public:
+		//! A single component in a solution
 		struct Component
 		{
 			int num;
 			double scale;
 		};
 
+		//! A solution whose components would fill the desired ring space.
 		class Solution
 		{
 			public:
-				// Components of this solution
+				//! @returns components of this solution
 				inline const QVector<Component>& getComponents() const
 				{
 					return m_components;
 				}
 
-				// Add a component to this solution
+				//! Add a component to this solution
 				inline void addComponent (const Component& a)
 				{
 					m_components.push_back (a);
 				}
 
-				// Compare solutions
-				bool isBetterThan (const Solution* other) const;
+				//! @brief Compare solutions.
+				//!
+				//! Compares this solution with @c other and determines which
+				//! one is superior.
+				//!
+				//! A solution is considered superior if solution has less
+				//! components than the other one. If both solution have an
+				//! equal amount components, the solution with a lesser maximum
+				//! ring number is found superior, as such solutions should
+				//! yield less new primitives and cleaner definitions.
+				//!
+				//! The solution which is found superior to every other solution
+				//! will be the one returned by @c RingFinder::bestSolution().
+				//!
+				//! @param other the solution to check against
+				//! @returns whether this solution is considered superior
+				//! @returns to @c other.
+				//!
+				bool isSuperiorTo (const Solution* other) const;
 
 			private:
 				QVector<Component> m_components;
 		};
 
+		//! Constructs a ring finder.
 		RingFinder() {}
+
+		//! @brief Tries to find rings between @c r0 and @c r1.
+		//!
+		//! This is the main algorithm of the ring finder. It tries to use math
+		//! to find the one ring between r0 and r1. If it fails (the ring number
+		//! is non-integral), it finds an intermediate radius (ceil of the ring
+		//! number times scale) and splits the radius at this point, calling this
+		//! function again to try find the rings between r0 - r and r - r1.
+		//!
+		//! This does not always yield into usable results. If at some point r ==
+		//! r0 or r == r1, there is no hope of finding the rings, at least with
+		//! this algorithm, as it would fall into an infinite recursion.
+		//!
+		//! @param r0 the lower radius of the ring space
+		//! @param r1 the higher radius of the ring space
+		//! @returns whether it was possible to find a solution for the given
+		//! @returns ring space.
+		//!
 		bool findRings (double r0, double r1);
 
+		//! @returns the solution that was considered best. Returns @c null
+		//! @returns if no suitable solution was found.
+		//! @see @c RingFinder::Solution::isSuperiorTo()
 		inline const Solution* bestSolution()
 		{
 			return m_bestSolution;
 		}
 
+		//! @returns all found solutions. The list is empty if no solutions
+		//! @returns were found.
 		inline const QVector<Solution>& allSolutions() const
 		{
 			return m_solutions;
 		}
 
-		inline bool operator() (double r0, double r1)
-		{
-			return findRings (r0, r1);
-		}
-
 	private:
 		QVector<Solution> m_solutions;
 		const Solution*   m_bestSolution;
 		int               m_stack;
 
+		//! Helper function for @c findRings
 		bool findRingsRecursor (double r0, double r1, Solution& currentSolution);
 };