From 9b633ba807c15f0120cbb8c23a40dbf7cabd4d68 Mon Sep 17 00:00:00 2001
From: Philip Chimento <philip.chimento@gmail.com>
Date: Fri, 8 Jul 2011 00:08:51 +0200
Subject: [PATCH] Added draft docs for new functions and gestalt selectors

---
 docs/reference/chimara-docs.sgml    |  2 +-
 docs/reference/chimara-sections.txt |  7 ++++++
 libchimara/doc.c                    | 35 ++++++++++++++++++++++-------
 libchimara/schannel.c               | 10 ++++-----
 4 files changed, 40 insertions(+), 14 deletions(-)

diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml
index 43dbffa..c98d874 100644
--- a/docs/reference/chimara-docs.sgml
+++ b/docs/reference/chimara-docs.sgml
@@ -105,7 +105,7 @@
     </chapter>
     
     <!-- Chapter 8. Sound -->
-    <chapter>
+    <chapter id="chimara-chapter-Sound">
       <title>Sound</title>
       <xi:include href="glk-sound-resources.sgml"/>
       <xi:include href="xml/glk-sound-channels.xml"/>
diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt
index 6952d18..74e9e6a 100644
--- a/docs/reference/chimara-sections.txt
+++ b/docs/reference/chimara-sections.txt
@@ -130,6 +130,7 @@ gestalt_MouseInput
 gestalt_Timer
 gestalt_Graphics
 gestalt_DrawImage
+gestalt_Sound2
 gestalt_Sound
 gestalt_SoundVolume
 gestalt_SoundNotify
@@ -494,6 +495,7 @@ GLK_MODULE_IMAGE
 <FILE>glk-sound-channels</FILE>
 <TITLE>Creating and Destroying Sound Channels</TITLE>
 glk_schannel_create
+glk_schannel_create_ext
 glk_schannel_destroy
 </SECTION>
 
@@ -502,8 +504,12 @@ glk_schannel_destroy
 <TITLE>Playing Sounds</TITLE>
 glk_schannel_play
 glk_schannel_play_ext
+glk_schannel_play_multi
 glk_schannel_stop
+glk_schannel_pause
+glk_schannel_unpause
 glk_schannel_set_volume
+glk_schannel_set_volume_ext
 glk_sound_load_hint
 </SECTION>
 
@@ -518,6 +524,7 @@ glk_schannel_get_rock
 <FILE>glk-sound-testing</FILE>
 <TITLE>Testing for Sound Capabilities</TITLE>
 GLK_MODULE_SOUND
+GLK_MODULE_SOUND2
 </SECTION>
 
 <SECTION>
diff --git a/libchimara/doc.c b/libchimara/doc.c
index 4b0a273..f058e27 100644
--- a/libchimara/doc.c
+++ b/libchimara/doc.c
@@ -1045,10 +1045,15 @@
  * SECTION:glk-sound-testing
  * @short_description: Checking whether the library supports sound
  *
- * Before calling Glk sound functions, you should use the %gestalt_Sound
- * selector. To test for additional capabilities, you can use the 
- * %gestalt_SoundMusic, %gestalt_SoundVolume, and %gestalt_SoundNotify 
- * selectors.
+ * Before calling Glk sound functions, you should use the %gestalt_Sound2
+ * selector.
+ *
+ * Earlier versions of the Glk spec defined separate selectors for various
+ * optional capabilities. This has proven to be an unnecessarily confusing
+ * strategy, and is no longer used. The %gestalt_Sound, %gestalt_SoundMusic,
+ * %gestalt_SoundVolume, and %gestalt_SoundNotify selectors still exist, but you
+ * should not need to test them; the %gestalt_Sound2 selector covers all of
+ * them.
  */
 
 /**
@@ -1577,10 +1582,24 @@
  * may implement both, neither, or only one.  
  */
 
+/**
+ * gestalt_Sound2:
+ *
+ * You can test whether the library supports sound:
+ * |[
+ * glui32 res;
+ * res = glk_gestalt(gestalt_Sound2, 0);
+ * ]|
+ * This returns 1 if the overall suite of sound functions is available. This
+ * includes all the functions defined in <link
+ * linkend="chimara-chapter-Sound">this chapter</link>. It also includes the
+ * capabilities described below under %gestalt_SoundMusic, %gestalt_SoundVolume,
+ * and %gestalt_SoundNotify.
+ */
+
 /**
  * gestalt_Sound:
  *
- * You can test whether the library supports sound: 
  * |[
  * glui32 res;
  * res = glk_gestalt(gestalt_Sound, 0);
@@ -1592,7 +1611,7 @@
  * glk_sound_load_hint().
  *
  * If this selector returns 0, you should not try to call these functions. They 
- * may have no effect, or they may cause a run-time error. 
+ * may have no effect, or they may cause a run-time error.
  */
 
 /**
@@ -1605,7 +1624,7 @@
  * res = glk_gestalt(gestalt_SoundVolume, 0);
  * ]|
  * This selector returns 1 if the glk_schannel_set_volume() function works. If 
- * it returns zero, glk_schannel_set_volume() has no effect.     
+ * it returns zero, glk_schannel_set_volume() has no effect.
  */
 
 /**
@@ -1617,7 +1636,7 @@
  * res = glk_gestalt(gestalt_SoundNotify, 0);
  * ]| 
  * This selector returns 1 if the library supports sound notification events. If
- * it returns zero, you will never get such events. 
+ * it returns zero, you will never get such events.
  */
 
 /**
diff --git a/libchimara/schannel.c b/libchimara/schannel.c
index 38561dc..1005778 100644
--- a/libchimara/schannel.c
+++ b/libchimara/schannel.c
@@ -476,11 +476,11 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
 
 /**
  * glk_schannel_play_multi:
- * @chanarray:
- * @chancount:
- * @sndarray:
- * @soundcount:
- * @notify:
+ * @chanarray: Array of #schanid_t structures.
+ * @chancount: Length of @chanarray.
+ * @sndarray: Array of sound resource numbers.
+ * @soundcount: Length of @sndarray, must be equal to @chanarray.
+ * @notify: If nonzero, request a notification when each sound finishes.
  * 
  * [DRAFT SPEC]
  *
-- 
2.30.2