Library: Update doxygen documentation

Also, remove the library section from the DESIGN document.

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

DESIGN

@@ -66,99 +66,6 @@ Callbacks:
 
 
 
-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
-	of managing a library queue used by the UI.  This queue has a special
-	file format, and will be saved to the file "library.q".
-
-- Queue:
-	class LibraryQueue : public Queue {
-	public:
-		LibraryQueue();
-		save();
-		load();
-		set_flag(queue_flag);
-		unset_flag(queue_flag);
-		sort(sort_t, bool);
-	};
-
-	File << flags << _sort_order.size()
-	File << _sort_order[N].field << _sort_order[N].ascending << ...
-
-- Validation:
-	Use a single idle function to loop over each track in the track
-	database.  Check if the track still exists in the filesystem and remove
-	it from the tagdb if not.
-
-- Updating:
-	Scan over all files in the current directory directory.
-	For each encountered directory:
-		Use the idle queue to call the update function with the new
-		directory as the "current" directory.
-	For each encountered file:
-		Attempt to add the file to the track_db.
-	Commit the database if at least one new file has been added.
-
-- Testing:
-	The script tests/library/gen_library.sh will create a sample library
-	in the /tmp/ directory for testing purposes.  All the track files are
-	complete silence, but the script will fake up tags for each file.
-
-	To test importing, create several mock library files and copy them to
-	~/.ocarina-test/library/ and attempt to read them in.
-
-- LibraryQueue API:
-	LibraryQueue :: LibraryQueue();
-		Initialize a Queue with the flags Q_ENABLED and Q_REPEAT.  The
-		default sorting order should be artist, year, track.
-
-	LibraryQueue :: save();
-		Write a library queue to disk.
-
-	LibraryQueue :: load();
-		Read a library queue from disk.
-
-	LibraryQueue :: set_flag(queue_flag f);
-	LibraryQueue :: unset_flag(queue_flag f);
-	LibraryQueue :: sort(sort_t field, bool reset);
-		These functions are wrappers around the default Queue
-		implementation.  First call the original function, then use
-		save() to store the changes.
-
-- API
-	void library :: init();
-		Scan the tagdb track list, and add each track to the library
-		queue.
-
-	Library *library :: add(string dir);
-		If dir is not a directory:
-			return NULL
-
-		Add a new path to the tag database, trigger an update, and
-		then return the corresponding Library tag to the caller.
-
-	void library :: remove(Library *library);
-		Invalidate a library_db row and all tracks owned by that path.
-		Do not use the library pointer after calling this function.
-
-	void library :: update(Library *library);
-		First, validate all tracks in the given library.
-		Next, trigger an update on the given library.
-
-	void library :: update_all();
-		Update all valid library paths.
-
-	void library :: set_enabled(Library *library, bool enabled);
-		Toggle if a library path is enabled or not.  A disabled
-		library path will have its tracks removed from the
-		LibraryQueue.
-
-	Queue *library :: get_queue();
-		Return the LibraryQueue to the caller.
-
-
-
 Playlist:
 	Playlists are a new feature in Ocarina 6 and are modeled after Gmail
 	labels.  Ocarina 6.2 will support two different playlists that the

include/core/library.h

@@ -10,13 +10,22 @@
 
 
 /**
- * Namespace for library access.
+ * The Library is in charge of scanning and updating Library tags along
+ * with every other tag in the tag database.  This code will also manage
+ * a special Queue used by the UI to display all enabled Tracks.
+ *
+ * The library queue is dynamic, so saving involves only storing the current
+ * flags and sort order.
+ *
+ * 	... << flags << _sort_order.size()
+ * 	... << _sort_order[N].field << _sort_order[N].ascending << ...
  */
 namespace library
 {
 
 	/**
-	 * Initialize the library queue with all the tracks in the tagdb.
+	 * Scan over every Track tag and add each enabled Track to the
+	 * library queue.
 	 */
 	void init();
 
@@ -24,31 +33,38 @@ namespace library
 	 * Add a new directory to the library.
 	 *
 	 * @param  dir  The directory that should be scanned.
-	 * @return The newly created library object.
+	 * @return The newly created Library tag or NULL if a
+	 *         tag could not be created.
 	 */
 	Library *add(const std::string &);
 
 	/**
-	 * Remove a library from the database.
+	 * Remove a Library tag from the database along with every
+	 * Track associated with this library.
 	 *
 	 * @param  library  The library path that should be removed.
 	 */
 	void remove(Library *);
 
 	/**
-	 * Update a specific library path.
+	 * First, scan over every Track in the database and remove
+	 * tracks that no longer exist in the filesystem.
+	 *
+	 * Next, scan over every file in the Library's root directory
+	 * and create new Track tags for every file found.
 	 *
 	 * @param  library  The library path that should be updated.
 	 */
 	void update(Library *);
 
 	/**
-	 * Rescan and update all library paths.
+	 * Call library :: update() on all Library tags.
 	 */
 	void update_all();
 
 	/**
-	 * Use to enable or disable a library path.
+	 * Use to enable or disable a library path.  When a Library path
+	 * is disabled, its tracks will be removed from the Library queue.
 	 *
 	 * @param  library  The library to be enabled or disabled.
 	 * @param  enabled  Set to true if the library should be enabled,