From 0359b59b8e3fef5623f9e7f49b02379b89599040 Mon Sep 17 00:00:00 2001
From: Edouard DUPIN <yui.heero@gmail.com>
Date: Thu, 15 Sep 2016 21:50:08 +0200
Subject: [PATCH] [DEV] create basic documentation

---
 audio/ess/ess.h   |  77 ++++++++++++++++++++++++++++++++++-
 doc/build.md      |  82 +++++++++++++++++++++++++++++++++++++
 doc/mainpage.md   |  58 ++++++++++++++++++++++++++
 doc/tutorial.md   | 101 ++++++++++++++++++++++++++++++++++++++++++++++
 doxy_audio-ess.py |  35 ++++++++++++++++
 5 files changed, 352 insertions(+), 1 deletion(-)
 create mode 100644 doc/build.md
 create mode 100644 doc/mainpage.md
 create mode 100644 doc/tutorial.md
 create mode 100644 doxy_audio-ess.py

diff --git a/audio/ess/ess.h b/audio/ess/ess.h
index 6dffa38..039fa75 100644
--- a/audio/ess/ess.h
+++ b/audio/ess/ess.h
@@ -8,28 +8,103 @@
 #include <etk/types.h>
 #include <audio/ess/effects.h>
 #include <audio/ess/music.h>
-
+/**
+ * @brief Audio library namespace
+ */
 namespace audio {
+	/**
+	 * @brief Audio-ess library namespace
+	 */
 	namespace ess {
+		/**
+		 * @brief Initialize the Ess singleton (Only one interface for all the Process)
+		 */
 		void init();
+		/**
+		 * @brief Release the Ess singleton (Only one interface for all the Process)
+		 */
 		void unInit();
 		
+		/**
+		 * @brief Parse a JSON configuration data of a soundset
+		 * @param[in] _data JSON string data to parse
+		 */
 		void soundSetParse(const std::string& _data);
+		/**
+		 * @brief Parse a configuration file of a soundset
+		 * @param[in] _file JSON file to parse
+		 */
 		void soundSetLoad(const std::string& _file);
 		
+		/**
+		 * @brief Play a music with his name
+		 * @param[in] _name Name of the music (not the Path)
+		 */
 		void musicPlay(const std::string& _name);
+		/**
+		 * @brief Stop the music played
+		 */
 		void musicStop();
+		/**
+		 * @brief Set the music volume
+		 * @param[in] _dB apply decibel volume at the music [-100..100]
+		 */
 		void musicSetVolume(float _dB);
+		/**
+		 * @brief Get the current music volume
+		 * @return Volume in dB of the music
+		 */
 		float musicGetVolume();
+		/**
+		 * @brief Set mute state of the music
+		 * @param[in] _mute New mute status
+		 */
 		void musicSetMute(bool _mute);
+		/**
+		 * @brief Get the current Mute status of the music
+		 * @return true The music is muted
+		 * @return false The music is active
+		 */
 		bool musicGetMute();
 		
+		/**
+		 * @brief Get the Unique ID of an effect
+		 * @param[in] _name Name of the effects
+		 * @return the effect ID or -1 if it does not exist...
+		 */
 		int32_t effectGetId(const std::string& _name);
+		/**
+		 * @brief Play an effect with his ID
+		 * @param[in] _id Id of the effect to play
+		 * @param[in] _pos position of the efffect is played (not used / not implemented)
+		 */
 		void effectPlay(int32_t _id, const vec3& _pos=vec3(0,0,0));
+		/**
+		 * @brief Play an effect with his name
+		 * @param[in] _name Name of the effect to play
+		 * @param[in] _pos position of the efffect is played (not used / not implemented)
+		 */
 		void effectPlay(const std::string& _name, const vec3& _pos=vec3(0,0,0));
+		/**
+		 * @brief Set the effects volume
+		 * @param[in] _dB apply decibel volume at the effects [-100..100]
+		 */
 		void effectSetVolume(float _dB);
+		/**
+		 * @brief Get the current effects volume
+		 * @return Volume in dB of the effects
+		 */
 		float effectGetVolume();
+		/**
+		 * @brief Set mute state of the effects
+		 * @param[in] _mute New mute status
+		 */
 		void effectSetMute(bool _mute);
+		/**
+		 * @brief Get the current Mute status of the effects
+		 * @return true The effects is muted
+		 * @return false The effects is active
+		 */
 		bool effectGetMute();
 	}
 }
diff --git a/doc/build.md b/doc/build.md
new file mode 100644
index 0000000..e517ce7
--- /dev/null
+++ b/doc/build.md
@@ -0,0 +1,82 @@
+Build lib & build sample                           {#audio_ess_build}
+========================
+
+@tableofcontents
+
+Download:                                          {#audio_ess_build_download}
+=========
+
+ege use some tools to manage source and build it:
+
+need google repo:                                  {#audio_ess_build_download_repo}
+-----------------
+
+see: http://source.android.com/source/downloading.html#installing-repo
+
+On all platform:
+```{.sh}
+	mkdir ~/.bin
+	PATH=~/.bin:$PATH
+	curl https://storage.googleapis.com/git-repo-downloads/repo > ~/.bin/repo
+	chmod a+x ~/.bin/repo
+```
+
+On ubuntu
+```{.sh}
+	sudo apt-get install repo
+```
+
+On archlinux
+```{.sh}
+	sudo pacman -S repo
+```
+
+lutin (build-system):                              {#audio_ess_build_download_lutin}
+---------------------
+
+```{.sh}
+	pip install lutin --user
+	# optionnal dependency of lutin (manage image changing size for application release)
+	pip install pillow --user
+```
+
+
+dependency:                                        {#audio_ess_build_download_dependency}
+-----------
+
+```{.sh}
+	mkdir -p WORKING_DIRECTORY/framework
+	cd WORKING_DIRECTORY/framework
+	repo init -u git://github.com/atria-soft/manifest.git
+	repo sync -j8
+	cd ../..
+```
+
+sources:                                           {#audio_ess_build_download_sources}
+--------
+
+They are already download in the repo manifest in:
+
+```{.sh}
+	cd WORKING_DIRECTORY/framework/musicdsp/audio-ess
+```
+
+Build:                                             {#audio_ess_build_build}
+======
+
+you must stay in zour working directory...
+```{.sh}
+	cd WORKING_DIRECTORY
+```
+
+library:                                           {#audio_ess_build_build_library}
+--------
+
+```{.sh}
+	lutin -mdebug audio-ess
+```
+
+Sample:                                            {#audio_ess_build_build_sample}
+-------
+
+No sample availlable now
diff --git a/doc/mainpage.md b/doc/mainpage.md
new file mode 100644
index 0000000..411dce0
--- /dev/null
+++ b/doc/mainpage.md
@@ -0,0 +1,58 @@
+AUDIO-ESS library                                {#mainpage}
+=================
+
+@tableofcontents
+
+What is AUDIO-ESS:                               {#audio_ess_mainpage_what}
+==================
+
+AUDIO-ESS, or Ewol Sound Set interface is designed to be a 'small game' audio effects engine. 
+==> fast to generate sound without attention at how thay are play and do not pay attention at the stop.
+
+
+What it does:                               {#audio_ess_mainpage_what_it_does}
+=============
+
+  - Load ogg/wav efffects and stay ready to play it
+  - play file without latency
+  - Manage a basic soundset
+
+AUDIO-ESS is dependent of the STL (compatible with MacOs stl (CXX))
+
+What languages are supported?                    {#audio_ess_mainpage_language}
+=============================
+
+AUDIO-ESS is written in C++.
+
+
+Are there any licensing restrictions?            {#audio_ess_mainpage_license_restriction}
+=====================================
+
+AUDIO-ESS is **FREE software** and _all sub-library are FREE and staticly linkable !!!_
+
+
+License (APACHE-2.0)                             {#audio_ess_mainpage_license}
+====================
+
+Copyright AUDIO-ESS Edouard DUPIN
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+<http://www.apache.org/licenses/LICENSE-2.0>
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+Other pages                              {#audio_ess_mainpage_sub_page}
+===========
+
+  - @ref audio_ess_build
+  - @ref audio_ess_tuto
+  - [**ewol coding style**](http://atria-soft.github.io/ewol/ewol_coding_style.html)
+
diff --git a/doc/tutorial.md b/doc/tutorial.md
new file mode 100644
index 0000000..bf1d63d
--- /dev/null
+++ b/doc/tutorial.md
@@ -0,0 +1,101 @@
+Tutoral: use sound-set                              {#audio_ess_tuto}
+======================
+
+@tableofcontents
+
+Objectifs:                                          {#audio_ess_tuto_objectif}
+==========
+
+  - Understand config file
+  - Create a simple playing sounds
+
+Create a configuration file                         {#audio_ess_tuto_config_file}
+===========================
+
+configuration file is really simple:
+```{.sh}
+soundSet.json
+```
+it contain 2 mains object:
+  - **musics:** That containig the list of all music files
+  - **effects:** That contain all effects files
+
+A simple example:
+```{.json}
+{
+	musics:{
+		"BG-1":"DATA:audio/Clean Soul.ogg"
+		"BG-22":"DATA:audio/Dark knight.ogg"
+	},
+	effects:{
+		"end":"DATA:audio/end.wav",
+		"error":"DATA:audio/error.wav",
+		"levelup":"DATA:audio/levelup.wav",
+		"ok":"DATA:audio/ok.wav"
+	}
+}
+```
+
+what you need to do first:                          {#audio_ess_tuto_include}
+==========================
+
+Include and basic init:
+```{.cpp}
+#include <audio/ess/ess.h>
+
+//in the main application:
+int main(...) {
+	audio::ess::init();
+	/*
+	 * Do your stuff
+	 */
+	audio::ess::unInit();
+	return 0;
+}
+
+```
+
+Select your sound set file:
+```{.cpp}
+	audio::ess::soundSetLoad("DATA:soundSet.json");
+```
+
+Play a background music:                            {#audio_ess_tuto_play_music}
+========================
+
+Start playing:
+```{.cpp}
+	audio::ess::musicPlay("BG-22");
+```
+
+Stop playing:
+```{.cpp}
+	audio::ess::musicStop();
+```
+
+Change volume: (reduce at -5dB)
+```{.cpp}
+	audio::ess::musicSetVolume(-5.0f);
+```
+
+Play an effect:                                     {#audio_ess_tuto_play_effect}
+===============
+
+Start playing:
+```{.cpp}
+	audio::ess::effectPlay("error");
+	sleep(1);
+	audio::ess::effectPlay("levelup");
+```
+
+or (faster way):
+```{.cpp}
+	int32_t effectId = audio::ess::effectGetId("error");
+	audio::ess::effectPlay(effectId);
+```
+**Note:** An effect can not stopped ...
+
+Change volume: (reduce at -5dB)
+```{.cpp}
+	audio::ess::effectSetVolume(-5.0f);
+```
diff --git a/doxy_audio-ess.py b/doxy_audio-ess.py
new file mode 100644
index 0000000..3a698d3
--- /dev/null
+++ b/doxy_audio-ess.py
@@ -0,0 +1,35 @@
+#!/usr/bin/python
+import os
+import doxy.module as module
+import doxy.debug as debug
+import doxy.tools as tools
+
+def create(target, module_name):
+	my_module = module.Module(__file__, module_name)
+	my_module.set_version("version.txt")
+	my_module.set_title("audio-ess: ewol sound set")
+	my_module.set_website("http://musicdsp.github.io/" + module_name)
+	my_module.set_website_sources("http://github.com/musicdsp/" + module_name)
+	my_module.add_path([
+	    "audio",
+	    "doc"
+	    ])
+	my_module.add_sample_path([
+	    "sample",
+	    ])
+	my_module.add_depend([
+	    'audio-river',
+	    'ejson'
+	    ])
+	my_module.add_exclude_symbols([
+	    '*operator<<*',
+	    ])
+	my_module.add_exclude_file([
+	    'debug.h',
+	    ])
+	my_module.add_file_patterns([
+	    'ess.h',
+	    '*.md',
+	    ])
+	
+	return my_module
\ No newline at end of file