# HG changeset patch # User Santeri Piippo # Date 1394033367 -7200 # Node ID b87941923eb4744293dfc95ded39f466799f7f6f # Parent 1ccb092cebed782a06eaaa1675a04a7452999732 - made MessageLog.h and RingFinder.h suitable for doxygen diff -r 1ccb092cebed -r b87941923eb4 src/MessageLog.cc --- 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) { diff -r 1ccb092cebed -r b87941923eb4 src/MessageLog.h --- 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& getLines() const; private: - QList m_lines; - QTimer* m_ticker; + QList m_lines; + QTimer* m_ticker; private slots: + //! Ticks the manager. This is called by the timer to update + //! the messages. void tick(); }; diff -r 1ccb092cebed -r b87941923eb4 src/misc/RingFinder.cc --- 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) { diff -r 1ccb092cebed -r b87941923eb4 src/misc/RingFinder.h --- 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& 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 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& allSolutions() const { return m_solutions; } - inline bool operator() (double r0, double r1) - { - return findRings (r0, r1); - } - private: QVector m_solutions; const Solution* m_bestSolution; int m_stack; + //! Helper function for @c findRings bool findRingsRecursor (double r0, double r1, Solution& currentSolution); };