Add doxygen documentation for audio.h, core.h, and version.h

I want to have all of Ocarina documented in the code, rather than in a
difficult-to-maintain DESIGN file.  Let's get going on that!

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

.gitignore

@@ -13,3 +13,5 @@ tests/*/*-lib
 *.gcda
 *.gcno
 core.*
+html/
+latex/

core/audio.cpp

@@ -1,4 +1,5 @@
-/*
+/**
+ * @file
  * Copyright 2013 (c) Anna Schumaker.
  */
 #include <core/audio.h>

core/core.cpp

@@ -1,4 +1,5 @@
-/*
+/**
+ * @file
  * Copyright 2014 (c) Anna Schumaker.
  */
 #include <core/audio.h>

include/core/audio.h

@@ -1,4 +1,5 @@
-/*
+/**
+ * @file
  * Copyright 2013 (c) Anna Schumaker.
  */
 #ifndef OCARINA_CORE_AUDIO_H
@@ -7,27 +8,97 @@
 #include <core/tags.h>
 #include <string>
 
+/**
+ * Namespace for higher-level audio controls.
+ */
 namespace audio
 {
 
+	/**
+	 * Initializes the audio layer and currently configured audio driver.
+	 *
+	 * @param  argc  Pointer to the argc initially passed to core :: init().
+	 * @param  argv  Pointer to the argv initially passed to core :: init().
+	 */
 	void init(int *, char ***);
 
+	/**
+	 * Begin playback.
+	 */
 	void play();
+
+	/**
+	 * Pause playback.
+	 */
 	void pause();
+
+	/**
+	 * Seek to a specific point in the track.
+	 *
+	 * @param  pos  Offset (in nanoseconds) from the beginning of the track.
+	 */
 	void seek_to(long);
+
+	/**
+	 * Stop playback (equivalent to pause(); seek_to(0);).
+	 */
 	void stop();
 
+	/**
+	 * @return The current position of the audio playback (in nanoseconds).
+	 */
 	long position();
+
+	/**
+	 * @return The duration of the currently loaded track (in nanoseconds).
+	 */
 	long duration();
+
+	/**
+	 * @return The current audio position, in a human readable format.
+	 */
 	std::string position_str();
 
+	/**
+	 * Find and load the next track that should be played.
+	 */
 	void next();
+
+	/**
+	 * Call the deck :: previous() function and load the result.
+	 */
 	void prev();
+
+	/**
+	 * Load a specific track for playback.
+	 */
 	void load_track(Track *track);
+
+	/**
+	 * @return A pointer to the currently playing track object.
+	 */
 	Track *current_track();
 
+	/**
+	 * Configure the automatic pausing feature.
+	 *
+	 * @param  enabled  Set to true to enable pausing, false to disable.
+	 * @param  n  Number of tracks to play before pausing.
+	 */
 	void pause_after(bool, unsigned int);
+
+	/**
+	 * Call to find the current automatic pausing state.
+	 *
+	 * @return True if automatic pausing is enabled, false otherwise.
+	 */
 	bool pause_enabled();
+
+	/**
+	 * Call to find the number of tracks remaining before pausing.
+	 *
+	 * @return The number of tracks before pausing.
+	 */
 	unsigned int pause_count();
 };
 

include/core/core.h

@@ -1,12 +1,23 @@
-/*
+/**
+ * @file
  * Copyright 2014 (c) Anna Schumaker.
  */
 #ifndef OCARINA_CORE_CORE_H
 #define OCARINA_CORE_CORE_H
 
+/**
+ * Namespace for basic core library functions.
+ */
 namespace core
 {
 
+	/**
+	 * Initializes all components of the core library, including reading
+	 * databases from disk and setting up gstreamer.
+	 *
+	 * @param  argc  Pointer to the argc initially passed to main()
+	 * @param  argv  Pointer to the argv initially passed to main()
+	 */
 	void init(int *, char ***);
 
 }

include/core/version.h

@@ -1,9 +1,15 @@
-/*
+/**
+ * @file
  * Copyright 2013 (c) Anna Schumaker.
  */
 #ifndef OCARINA_CORE_VERSION_H
 #define OCARINA_CORE_VERSION_H
 
+/**
+ * Find the current version of Ocarina.
+ *
+ * @return The current Ocarina version.
+ */
 static inline const char *get_version()
 {
 	return CONFIG_VERSION;