Mercurial > ldforge / file diff

--- a/src/misc/RingFinder.h	Sun Mar 09 14:04:06 2014 +0200
+++ b/src/misc/RingFinder.h	Sun Mar 09 14:59:46 2014 +0200
@@ -16,73 +16,114 @@
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#ifndef LDFORGE_MISC_RINGFINDER_H
-#define LDFORGE_MISC_RINGFINDER_H
+#pragma once
 
 #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);
 };
 
 extern RingFinder g_RingFinder;
 
-#endif // LDFORGE_MISC_RINGFINDER_H
\ No newline at end of file