Queue: Update doxygen documentation

I also remove the related section of the DESIGN document.

Signed-off-by: Anna Schumaker <Anna@OcarinaProject.net>

DESIGN

@@ -66,162 +66,6 @@ Callbacks:
 
 
 
-Queue:
-	Queues are lists of songs that the user has requested to play.  They
-	are the main interface for all music played by Ocarina.
-
-- Flags:
-	enum queue_flag {
-		Q_ENABLED (1 << 0),
-		Q_RANDOM  (1 << 1),
-		Q_REPEAT  (1 << 2),
-		Q_NO_SORT (1 << 3),
-	};
-
-- Sorting:
-	enum sort_t {
-		SORT_ARTIST,
-		SORT_ALBUM,
-		SORT_COUNT,
-		SORT_GENRE,
-		SORT_LENGTH,
-		SORT_PLAYED,
-		SORT_TITLE,
-		SORT_TRACK,
-		SORT_YEAR,
-	};
-
-- Sort info:
-	struct sort_info {
-		sort_t field;
-		bool   ascending;
-	};
-
-- Sorting:
-	Sorting is done using std::stable_sort() to make sure that orders won't
-	change unexpectedly.
-
-- Queue:
-	class Queue {
-	protected:
-		vector<Track *> _tracks;
-		list<sort_t> _sort_order;
-		unsigned int _cur;
-		unsigned int _flags;
-		unsigned int _length;
-
-	public:
-		Queue();
-		Queue(unsigned int);
-		void read(File &);
-		void write(File &);
-
-		void set_flag(queue_flag);
-		void unset_flag(queue_flag);
-		bool has_flag(queue_flag);
-
-		unsigned int add(Track *);
-		void del(Track *);
-		void del(unsigned int);
-		void updated(Track *);
-		Track *next();
-
-		unsigned int size();
-		const std::string size_str();
-		const std::string length_str();
-
-		void sort(sort_t, bool);
-		Track *operator[](unsigned int);
-		void track_selected(unsigned int);
-	};
-
-File Format:
-	File << flags << tracks.size() << tracks[0] << tracks[1] << ... << tracks[N];
-
-- API
-	Queue :: Queue();
-		Initialize _flags = 0, _cur = -1, _length = 0, and empty sort
-		order.
-
-	Queue :: Queue(unsigned int flags);
-		Initialize _flags = flags, _cur = -1, _length = 0, and empty
-		sort order.
-
-	void Queue :: read(File &f);
-		Read queue from file.
-
-	void Queue :: write(File &f);
-		Write queue to file.
-
-	void Queue :: set_flag(queue_flag f);
-		Set the appropriate flag.
-
-	void Queue :: unset_flag(queue_flag f);
-		Unset the appropriate flag.
-
-	bool Queue :: has_flag(queue_flag f);
-		Return true if the queue has the flag enabled and false
-		otherwise.
-
-	unsigned int Queue :: add(Track *track);
-		Add a new track to the tracks vector and return the index.
-		Increase length by the length of the track.
-
-	void Queue :: del(Track *track);
-		Remove all instances of the requested track from the queue.
-
-	void Queue :: del(unsigned int queue_id);
-		Remove the track at the given index from the queue.
-
-	void Queue :: updated(Track *track);
-		Find all indexes of the updated track and notify the UI that
-		it has changed.
-
-	Track *Queue :: next();
-		Return the next track to play.
-
-		if (tracks.size() == 0)
-			return NULL;
-
-		if (flags & PL_RANDOM):
-			_cur += rand() % tracks.size();
-		else:
-			_cur += 1;
-
-		if (_cur >= tracks.size())
-			_cur -= tracks.size();
-		track = tracks[_cur];
-
-		if (!(flags & PL_REPEAT)):
-			del(_cur);
-		return track;
-
-	unsigned int Queue :: size();
-		Return the number of tracks currently on the queue.
-
-	const std::string Queue :: size_str();
-		Return the number of tracks currently on the queue, in string
-		form.
-
-	const std::string Queue :: length_str();
-		Return the remaining length of the queue in a human-readable
-		format.
-
-	void Queue :: sort(sort_t field, bool reset);
-		If the field is already in the sort order, toggle its
-		ascending value.  Otherwise, add a new sort field to the end
-		of the sort order with ascending set to true.  If reset is set
-		to true, clear the sorting list before appending.
-
-	Track *Queue :: operator[](unsigned int i);
-		Return the track and index i.
-
-	void Queue :: track_selected(unsigned int queue_id);
-		Set _cur to queue_id.  If PQ_REPEAT is not set, remove the
-		track from the queue.
-
-
-
 Library:
 	The library is in charge of scanning and updating library paths added
 	to the tag database.  In addition, the library layer is also in charge

core/queue.cpp

@@ -13,52 +13,50 @@
 #define O_HOURS   (60 * O_MINUTES)
 #define O_DAYS    (24 * O_HOURS)
 
+
+Queue :: Queue(unsigned int flags)
+       : _cur(-1), _flags(flags), _length(0)
+{}
+
 Queue :: Queue()
        : _cur(-1), _flags(0), _length(0)
-{
+{}
-}
-
-Queue :: Queue(unsigned int f)
-	 : _cur(-1), _flags(f), _length(0)
-{
-}
 
 Queue :: ~Queue()
-{
+{}
-}
 
-void Queue :: write(File &f)
+void Queue :: write(File &file)
 {
-	f << _flags << " " << _tracks.size();
+	file << _flags << " " << _tracks.size();
 	for (unsigned int i = 0; i < _tracks.size(); i++)
-		f << " " << _tracks[i]->index();
+		file << " " << _tracks[i]->index();
 }
 
-void Queue :: read(File &f)
+void Queue :: read(File &file)
 {
 	unsigned int n, id;
-	f >> _flags >> n;
+	file >> _flags >> n;
 	_tracks.resize(n);
 	for (unsigned int i = 0; i < n; i++) {
-		f >> id;
+		file >> id;
 		_tracks[i] = tags :: get_track(id);
 		_length += _tracks[i]->length();
 	}
 }
 
-void Queue :: set_flag(queue_flags f)
+void Queue :: set_flag(queue_flags flag)
 {
-	_flags |= f;
+	_flags |= flag;
 }
 
-void Queue :: unset_flag(queue_flags f)
+void Queue :: unset_flag(queue_flags flag)
 {
-	_flags &= ~f;
+	_flags &= ~flag;
 }
 
-bool Queue :: has_flag(queue_flags f)
+bool Queue :: has_flag(queue_flags flag)
 {
-	return (_flags & f) == (unsigned int)f;
+	return (_flags & flag) == (unsigned int)flag;
 }
 
 /*
@@ -167,9 +165,9 @@ void Queue :: del(Track *track)
 	}
 }
 
-void Queue :: del(unsigned int id)
+void Queue :: del(unsigned int index)
 {
-	_del_at(_tracks[id], id);
+	_del_at(_tracks[index], index);
 }
 
 void Queue :: updated(Track *track)
@@ -274,14 +272,14 @@ void Queue :: sort(sort_t field, bool reset)
 		get_callbacks()->on_queue_track_changed(this, i);
 }
 
-Track *Queue :: operator[](unsigned int i)
+Track *Queue :: operator[](unsigned int index)
 {
-	return _tracks[i];
+	return _tracks[index];
 }
 
-void Queue :: track_selected(unsigned int id)
+void Queue :: track_selected(unsigned int index)
 {
-	_cur = id;
+	_cur = index;
 	if (has_flag(Q_REPEAT) == false) {
 		del(_cur);
 		_cur--;

include/core/queue.h

@@ -49,15 +49,21 @@ struct sort_info {
 
 
 /**
- * Class defining playback queues.
+ * Queues are lists of songs that the user has requested to play next,
+ * although not necessarily in a specific order.
+ *
+ * When writing a Queue to disk: write out the _flags and size values
+ * first, followed by the list of track indexes.
+ *
+ * 	... << _flags << _tracks.size() << tracks[N]->index() << ...;
  */
 class Queue {
 protected:
-	std :: vector <Track *> _tracks;
+	std :: vector <Track *> _tracks; /**< List of tracks in this queue. */
-	std :: vector <struct sort_info> _sort_order;
+	std :: vector <struct sort_info> _sort_order; /**< Current sort settings */
-	unsigned int _cur;
+	unsigned int _cur;	/**< The index of the last track played. */
-	unsigned int _flags;
+	unsigned int _flags;	/**< Mask of queue_flags. */
-	unsigned int _length;
+	unsigned int _length;	/**< Total runtime of the queue. */
 
 	unsigned int find_sorted_id(Track *);
 	unsigned int _add_at(Track *, unsigned int);
@@ -65,56 +71,57 @@ protected:
 
 public:
 	/**
-	 * Default queue constructor.
+	 * Alternate queue constructor.
-	 */
+	 *
-	Queue();
+	 * @param  flags  Create a queue with _flags set to flags.
-
-	/**
-	 * Alternat queue constructor.
-	 * @param  f  Create a queue with flags set to f.
 	 */
 	Queue(unsigned int);
 
-	/**
+	Queue();  /**< Default queue constructor. */
-	 * Queue destructor.
+	~Queue(); /**< Queue destructor.          */
-	 */
-	~Queue();
 
 	/**
 	 * Write a queue to disk.
-	 * @param  f  File queue data will be written to.
+	 *
+	 * @param  file  File that Queue data will be written to.
 	 */
 	void write(File &);
 
 	/**
 	 * Read a queue from disk.
-	 * @param  f  File to read queue data from.
+	 *
+	 * @param  file  File to read Queue data from.
 	 */
 	void read(File &);
 
 
 	/**
 	 * Set a queue flag.
-	 * @param  f  queue_flag to set.
+	 *
+	 * @param  flag  queue_flag to set.
 	 */
 	virtual void set_flag(queue_flags);
 
 	/**
 	 * Clear a queue flag.
-	 * @param  f  queue_flag to clear.
+	 *
+	 * @param  flag  queue_flag to clear.
 	 */
 	virtual void unset_flag(queue_flags);
 
 	/**
 	 * Check if a queue has a specific flag set.
-	 * @param  f  queue_flag to check.
+	 *
-	 * @return true if queue_flag is set.
+	 * @param  flag  queue_flag to check.
+	 * @return true if queue_flag is set and false otherwise.
 	 */
 	bool has_flag(queue_flags);
 
 
 	/**
-	 * Add a track to the queue.
+	 * Add a track to the queue, possibly matching the
+	 * current sort order.
+	 *
 	 * @param  track  Track to add to the queue.
 	 * @return The index of the track in the queue.
 	 */
@@ -122,50 +129,65 @@ public:
 
 	/**
 	 * Remove all instances of a track from the queue.
+	 *
 	 * @param  track Track to remove from the queue.
 	 */
 	virtual void del(Track *);
 
 	/**
 	 * Remove a track based on its queue index.
+	 *
 	 * @param  index  Track index to remove from the queue.
 	 */
 	virtual void del(unsigned int);
 
 	/**
 	 * Signal to the queue that a track has been updated.
+	 *
 	 * @param  track  The track that has been modified.
 	 */
 	void updated(Track *);
 
 	/**
-	 * Pick the next track from the queue.
+	 * Pick the next track from the queue.  If Q_RANDOM is set then a
-	 * @return The next Track on the queue.
+	 * random Track will be returned, otherwise _cur will be incremented
+	 * and used to pick the next Track.  If Q_REPEAT is not set then
+	 * the chosen track will be removed from the queue.
+	 *
+	 * @return The next Track on the queue, or NULL if the Queue is empty.
 	 */
 	Track *next();
 
 
 	/**
 	 * Find the size of the queue.
+	 *
 	 * @return The number of tracks on the queue.
 	 */
 	unsigned int size();
 
 	/**
 	 * Find the size of the queue, as a string.
+	 *
 	 * @return The number of tracks on the queue, in string form.
 	 */
 	const std::string size_str();
 
 	/**
 	 * Find the runtime of the queue.
+	 *
 	 * @return The runtime of the queue, as a string.
 	 */
 	const std::string length_str();
 
 
 	/**
-	 * Add a new parameter for sorting the queue.
+	 * Add a new sort field to the queue.  If the field is already in the
+	 * _sort_order then it's ascending  or descending value will be toggled.
+	 *
+	 * If reset is set to True then the _sort_order will be cleared before
+	 * adding the new value.
+	 *
 	 * @param  field  Field to sort by.
 	 * @param  reset  Set to true if current sort data should be discarded.
 	 */
@@ -173,6 +195,7 @@ public:
 
 	/**
 	 * Access a track by index.
+	 *
 	 * @param  index  The index to look up.
 	 * @return  The track found at the requested index.
 	 */
@@ -180,7 +203,9 @@ public:
 
 	/**
 	 * Tell the queue that a track has been selected for playback without
-	 * calling Queue :: next().
+	 * calling Queue :: next().  If Q_REPEAT is not set then the Track
+	 * will be removed from the queue.
+	 *
 	 * @param  index  The index that is now playing.
 	 */
 	void track_selected(unsigned int);

tests/core/queue.cpp

@@ -15,8 +15,7 @@ unsigned int last_update = 0;
 Track *TRACK_NULL = NULL;
 
 
-class TestQueue : public Queue
+class TestQueue : public Queue {
-{
 public:
 	TestQueue() : Queue() {}
 	TestQueue(unsigned int f) : Queue(f) {}