From 53c1b1459979dfe5b8077bc4584f197bc46c8668 Mon Sep 17 00:00:00 2001
From: Torben Hohn <torbenh@gmx.de>
Date: Sun, 22 Nov 2009 07:55:15 +0100
Subject: [PATCH] add some docs...

---
 jack/jack.h  | 19 +++++++++++++++++++
 jack/types.h | 18 ++++++++++++++++++
 2 files changed, 37 insertions(+)

diff --git a/jack/jack.h b/jack/jack.h
index d04c765..cac92ef 100644
--- a/jack/jack.h
+++ b/jack/jack.h
@@ -1019,16 +1019,35 @@ void jack_set_info_function (void (*func)(const char *));
  */
 void jack_free(void* ptr);
 
+/**
+ * send a save or quit event, to all clients listening for session
+ * callbacks. the returned strings of the clients are accumulated and
+ * returned as an array of jack_session_command_t.
+ * its terminated by ret[i].uuid[0]='\0'
+ */
 
 jack_session_command_t *jack_session_notify (jack_client_t* client,
 					     jack_session_event_t code,
 					     const char *path ) JACK_WEAK_EXPORT;
 
+/**
+ * get the jack client name for a uuid
+ */
+
 char *jack_get_client_name_by_uuid( jack_client_t *client, const char *uuid ) JACK_WEAK_EXPORT;
 
+/**
+ * get some metadata cookie for client with uuid
+ */
+
 char *jack_get_cookie_by_uuid( jack_client_t *client,
 			       const char *uuid,
 			       const char *key ) JACK_WEAK_EXPORT;
+
+/**
+ * set metadata cookie on self
+ */
+
 int jack_client_set_cookie( jack_client_t *client,
 			    const char *key,
 			    const char *value ) JACK_WEAK_EXPORT;
diff --git a/jack/types.h b/jack/types.h
index 075e1e0..9634cae 100644
--- a/jack/types.h
+++ b/jack/types.h
@@ -372,6 +372,24 @@ typedef void (*JackShutdownCallback)(void *arg);
  */
 typedef void (*JackInfoShutdownCallback)(jack_status_t code, const char* reason, void *arg);
 
+/**
+ * Prototype for the client supplied function that is called
+ * whenever a session notification is sent via jack_session_notify().
+ * for a save event the client is required to save its state.
+ * it must save it into session_dir, and at least use prefix for the first
+ * part of the filename. (it is free to create a directory or create more
+ * files, as long as these start with prefix.)
+ * the prefix also acts as uuid, which the client needs to specify
+ * to jack_client_open()  upon session reload.
+ *
+ * the return value is a commandline, which will restore the state.
+ *
+ 
+ * @param code the type of the Event (Save or Quit)
+ * @param session_dir with trailing separator.
+ * @param prefix for saved files. 
+ * @param arg pointer to a client supplied structure
+ */
 
 typedef char *(*JackSessionCallback)(jack_session_event_t code, const char* session_dir, const char* prefix, void *arg);