From 3d00a83b6a17068a09dfaf4f441ce697156979f3 Mon Sep 17 00:00:00 2001
From: Anna Schumaker <Anna@OcarinaProject.net>
Date: Mon, 20 Oct 2014 21:37:58 -0400
Subject: [PATCH] driver: Add doxygen documentation

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

diff --git a/core/driver.cpp b/core/driver.cpp
index 258ac6d1..ac94fbd2 100644
--- a/core/driver.cpp
+++ b/core/driver.cpp
@@ -1,4 +1,5 @@
-/*
+/**
+ * @file
  * Copyright 2014 (c) Anna Schumaker.
  */
 #include <core/driver.h>
diff --git a/include/core/driver.h b/include/core/driver.h
index 538da906..e4fee543 100644
--- a/include/core/driver.h
+++ b/include/core/driver.h
@@ -1,4 +1,5 @@
-/*
+/**
+ * @file
  * Copyright 2014 (c) Anna Schumaker.
  */
 #ifndef OCARINA_CORE_DRIVER_H
@@ -6,26 +7,87 @@
 
 #include <string>
 
+/** Use to convert nanoseconds to seconds */
 static const unsigned long O_SECOND = 1000000000;
 
 
+/**
+ * Base class for different audio drivers.
+ */
 class Driver {
 protected:
+	/**
+	 * End-of-stream callback function.
+	 */
 	void (*on_eos)();
+
+	/**
+	 * Error handling callback function.
+	 */
 	void (*on_error)();
 
 public:
+	/**
+	 * Default Driver constructor.
+	 */
 	Driver();
+
+	/**
+	 * Driver destructor.
+	 */
 	~Driver();
+
+	/**
+	 * Initialize a driver
+	 * @param  argc  Argc passed to the application's main() function.
+	 * @param  argv  Argv passed to the applicaiton's main() function.
+	 * @param  eos_cb  End-of-stream callback function.
+	 * @param  error_cb  Callback function used when the audio library encounters an error.
+	 */
 	virtual void init(int *, char ***, void (*)(), void (*)()) = 0;
 
+
+	/**
+	 * Load an audio file for playback.
+	 * @param  file  Filepath of the track to load.
+	 */
 	virtual void load(const std::string &) = 0;
+
+	/**
+	 * Called to begin playback on the currently loaded track.
+	 * @return True if playback state was changed successfully, false otherwise.
+	 */
 	virtual bool play() = 0;
+
+	/**
+	 * Called to pause playback on the currently loaded track.
+	 * @return True if playback state was changed successfully, false otherwise.
+	 */
 	virtual bool pause() = 0;
+
+	/**
+	 * Called to check if the audio library is currently playing a track.
+	 * @return True if audio library is playing, false otherwise.
+	 */
 	virtual bool is_playing() = 0;
 
+
+	/**
+	 * Seek to a specific position in the current track.
+	 * @param  offset  Position from the beginning of the track where we will seek to, in nanoseconds.
+	 */
 	virtual void seek_to(long) = 0;
+
+	/**
+	 * Return the current position of the playback.
+	 * @return The current playback position, in nanoseconds.
+	 */
 	virtual long position() = 0;
+
+	/**
+	 * Return the duration of the currently loaded track.
+	 * @return The duration of the current track, in nanoseconds.
+	 */
 	virtual long duration() = 0;
 };
 
@@ -59,6 +121,9 @@ public:
 
 #include <gst/gst.h>
 
+/**
+ * Driver for the GStreamer audio library.
+ */
 class GSTDriver : public Driver
 {
 private:
@@ -67,27 +132,88 @@ private:
 	bool change_state(GstState state);
 
 public:
+	/**
+	 * GStreamer audio driver constructor.
+	 */
 	GSTDriver();
+
+	/**
+	 * GStreamer audio driver destructor.
+	 */
 	~GSTDriver();
+
+	/**
+	 * Called to initialize the GStreamer audio driver.
+	 * @param  argc  Argc passed to the application's main() function.
+	 * @param  argv  Argv passed to the applicaiton's main() function.
+	 * @param  eos_cb  End-of-stream callback function.
+	 * @param  error_cb  Callback function used when the audio library encounters an error.
+	 */
 	void init(int *, char ***, void (*)(), void (*)());
 
+	/**
+	 * Load a track into the gstreamer pipeline.
+	 * @param  filepath  The file to be loaded.
+	 */
 	void load(const std::string &);
+
+	/**
+	 * Begin playback on the GStreamer pipeline.
+	 * @return True if the state change was successful.
+	 */
 	bool play();
+
+	/**
+	 * Pause the GStreamer pipeline.
+	 * @return True if the state change was successful.
+	 */
 	bool pause();
+
+	/**
+	 * Check if the GStreamer pipeline is playing.
+	 * @return True if the pipeline is playing.
+	 */
 	bool is_playing();
 
+
+	/**
+	 * Seek to a specific position in the pipeline.
+	 * @param  offset  Offset from the beginning of the pipeline, in nanoseconds.
+	 */
 	void seek_to(long);
+
+	/**
+	 * Find the current playback position of the pipeline.
+	 * @return The current position of the pipeline, in nanoseconds.
+	 */
 	long position();
+
+	/**
+	 * Find the duration of the pipeline.
+	 * @return The duration of the pipeline, in nanoseconds.
+	 */
 	long duration();
 
+
+	/**
+	 * Called to handle messages from the GStreamer bus.
+	 * @param  message  The message to be handled.
+	 */
 	void on_message(GstMessage *);
 };
 #endif /* CONFIG_TEST */
 
 
+/**
+ * Namespace for audio driver access.
+ */
 namespace driver
 {
 
+	/**
+	 * Called to access an audio driver.
+	 * @return The current driver used by the application.
+	 */
 	Driver *get_driver();
 
 }