From 5f56118c040abe51f1e76ab0346903eb65e133be Mon Sep 17 00:00:00 2001
From: Anna Schumaker <Anna@OcarinaProject.net>
Date: Fri, 17 Oct 2014 09:42:45 -0400
Subject: [PATCH] queue:  Add doxygen documentation

Signed-off-by: Anna Schumaker <Anna@OcarinaProject.net>
---
 core/queue.cpp       |   3 +-
 include/core/queue.h | 122 ++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 123 insertions(+), 2 deletions(-)

diff --git a/core/queue.cpp b/core/queue.cpp
index cd3bfe68..dcb6ae27 100644
--- a/core/queue.cpp
+++ b/core/queue.cpp
@@ -1,4 +1,5 @@
-/*
+/**
+ * @file
  * Copyright 2013 (c) Anna Schumaker.
  */
 #include <core/callback.h>
diff --git a/include/core/queue.h b/include/core/queue.h
index 11367a03..d50fc007 100644
--- a/include/core/queue.h
+++ b/include/core/queue.h
@@ -1,4 +1,5 @@
-/*
+/**
+ * @file
  * Copyright 2013 (c) Anna Schumaker.
  */
 #ifndef OCARINA_CORE_QUEUE_H
@@ -10,20 +11,42 @@
 #include <vector>
 #include <list>
 
+/**
+ * Enum defining queue flags.
+ */
 enum queue_flags {
+	/** Queue is enabled. */
 	Q_ENABLED	= (1 << 0),
+
+	/** Queue will pick songs randomly. */
 	Q_RANDOM	= (1 << 1),
+
+	/** Queue will not remove songs when picked.  */
 	Q_REPEAT	= (1 << 2),
+
+	/** Queue will not be sorted. */
 	Q_NO_SORT	= (1 << 3),
 };
 
+
+/**
+ * Mask of valid flags.
+ */
 static const unsigned int Q_FLAG_MASK = Q_ENABLED | Q_RANDOM | Q_REPEAT | Q_NO_SORT;
 
+
+/**
+ * Struct for passing sort parameters.
+ */
 struct sort_info {
 	sort_t field;
 	bool   ascending;
 };
 
+
+/**
+ * Class defining playback queues.
+ */
 class Queue {
 protected:
 	std :: vector <Track *> _tracks;
@@ -37,28 +60,125 @@ protected:
 	void _del_at(Track *, unsigned int);
 
 public:
+	/**
+	 * Default queue constructor.
+	 */
 	Queue();
+
+	/**
+	 * Alternat queue constructor.
+	 * @param  f  Create a queue with flags set to f.
+	 */
 	Queue(unsigned int);
+
+	/**
+	 * Queue destructor.
+	 */
 	~Queue();
+
+	/**
+	 * Write a queue to disk.
+	 * @param  f  File queue data will be written to.
+	 */
 	void write(File &);
+
+	/**
+	 * Read a queue from disk.
+	 * @param  f  File to read queue data from.
+	 */
 	void read(File &);
 
+
+	/**
+	 * Set a queue flag.
+	 * @param  f  queue_flag to set.
+	 */
 	virtual void set_flag(queue_flags);
+
+	/**
+	 * Clear a queue flag.
+	 * @param  f  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.
+	 */
 	bool has_flag(queue_flags);
 
+
+	/**
+	 * Add a track to the queue.
+	 * @param  track  Track to add to the queue.
+	 * @return The index of the track in the queue.
+	 */
 	virtual unsigned int add(Track *);
+
+	/**
+	 * 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.
+	 * @return The next Track on the queue.
+	 */
 	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.
+	 * @param  field  Field to sort by.
+	 * @param  reset  Set to true if current sort data should be discarded.
+	 */
 	virtual void sort(sort_t, bool);
+
+	/**
+	 * Access a track by index.
+	 * @param  index  The index to look up.
+	 * @return  The track found at the requested index.
+	 */
 	Track *operator[](unsigned int);
+
+	/**
+	 * Tell the queue that a track has been selected for playback without
+	 * calling Queue :: next().
+	 * @param  index  The index that is now playing.
+	 */
 	void track_selected(unsigned int);
 };