updated DB schema documentation for PA module (included within its documentation)

db/schema/offline_winfo.xml

@@ -7,30 +7,37 @@
 
 ]>
 
-<table role="presence" xmlns:db="http://docbook.org/ns/docbook">
+<table role="presence">
 	
 	<name>offline_winfo</name>
 	
 	<!-- related to the version of presence snapshot -->
 	<version>5</version>
+	<description>Table used to store information about subscriptions to
+	"offline presentities". Data here can be manipulated using
+	functions <function>store_winfo</function> and
+	<function>dump_stored_winfo</function>.</description>
 
 	<column id="offline_winfo.uid">
 		<name>uid</name>
 		<name db="oracle">uuid</name>
 		<type>string</type>
 		<size>&id_len;</size>
+		<description>UID of presentity.</description>
 	</column>
 
 	<column>
 		<name>watcher</name>
 		<type>string</type>
 		<size>&uri_len;</size>
+		<description>Watcher's URI.</description>
 	</column>
 
 	<column>
 		<name>events</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Subscription event header (presence).</description>
 	</column>
 
 	<column>
@@ -38,6 +45,8 @@
 		<type>string</type>
 		<size>&domain_len;</size>
 		<null/>
+		<description>Presence domain (<emphasis>registrar</emphasis> or
+		<emphasis>jabber</emphasis>).</description>
 	</column>
 
 	<column>
@@ -45,18 +54,23 @@
 		<type>string</type>
 		<size>32</size>
 		<null/>
+		<description>Subscription status.</description>
 	</column>
 
 	<column>
 		<name>created_on</name>
 		<type>datetime</type>
 		<default>2006-01-31 13:13:13</default>
+		<description>Time of row creation used to discard expired rows. Row
+		expires when its creation time is older than configured
+		value.</description>
 	</column>
 
 	<column>
 		<name>expires_on</name>
 		<type>datetime</type>
 		<default>2006-01-31 13:13:13</default>
+		<description>Time when row expires.</description>
 	</column>
 
 	<column id="offline_winfo.dbid">
@@ -66,6 +80,7 @@
 		<type db="mysql">INT(10) UNSIGNED AUTO_INCREMENT</type>
 		<type db="postgres">SERIAL</type>
 		<type db="dbtext">int,auto</type>
+		<description>Auto-generated key.</description>
 	</column>
 
 	<index>

db/schema/presentity.xml

@@ -7,27 +7,32 @@
 
 ]>
 
-<table role="presence" xmlns:db="http://docbook.org/ns/docbook">
+<table role="presence">
 	
 	<name>presentity</name>
+	<description>Table holding presentities for PA module. It is basic PA table,
+	most of other PA tables are related to this one.</description>
 
 	<!-- related to the version of presence snapshot -->
 	<version>5</version>
     
 	<column id="presentity.pres_id">
 		<name>pres_id</name>
+		<description>Generated presentity identifier unique across pdomains.</description>
 		<type>string</type>
 		<size>64</size>
 	</column>
 
 	<column id="presentity.uri">
 		<name>uri</name>
+		<description>Presentity URI used when creating presentity.</description>
 		<type>string</type>
 		<size>&uri_len;</size>
 	</column>
 
 	<column id="presentity.uid">
 		<name>uid</name>
+		<description>Presentity UID (unique user identification in SER).</description>
 		<name db="oracle">uuid</name>
 		<type>string</type>
 		<size>&id_len;</size>
@@ -35,6 +40,9 @@
 
 	<column>
 		<name>pdomain</name>
+		<description><para>PA domain name. It represents separate "group" of
+		presentities. There can be two pdomains now - named
+		<emphasis>registrar</emphasis> and <emphasis>jabber</emphasis>.</para></description>
 		<type>string</type>
 		<size>128</size>
 	</column>
@@ -44,6 +52,11 @@
 	to know what is within them). -->
 	<column>
 		<name>xcap_params</name>
+		<description><para>XCAP parameters (in serialized form) used to
+		obtain authorization information.</para>
+		<para>Stored due to possibility to change user's XCAP parameters from script, but this is quite
+		ineffective and it will be thrown out because XCAP parameters are mostly
+		the same for all presentities.</para></description>
 		<type>binary</type>
 	</column>
 

db/schema/presentity_contact.xml

@@ -7,9 +7,11 @@
 
 ]>
 
-<table role="presence" xmlns:db="http://docbook.org/ns/docbook">
+<table role="presence">
 
 	<name>presentity_contact</name>
+	<description>Table holding published tuples (NOT tuples generated by
+	registrations).</description>
 	
 	<!-- related to the version of presence snapshot -->
 	<version>5</version>
@@ -19,6 +21,7 @@
 		<name>pres_id</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Presentity ID.</description>
 	</column>
 
 	<!-- basic status -->
@@ -26,18 +29,22 @@
 		<name>basic</name>
 		<type>int</type>
 		<size>3</size>
+		<description>Basic status as number. It can have values 0 (open) or 1
+		(closed).</description>
 	</column>
 
 	<column>
 		<name>expires</name>
 		<type>datetime</type>
 		<default>2004-05-28 21:32:15</default>
+		<description>Expiration value.</description>
 	</column>
 
 	<column>
 		<name>priority</name>
 		<type>float</type>
 		<default>0.5</default>
+		<description>Contact priority value.</description>
 	</column>
 
 	<column>
@@ -45,6 +52,7 @@
 		<type>string</type>
 		<size>&uri_len;</size>
 		<null/>
+		<description>Published contact information.</description>
 	</column>
 
 	<!-- tuple ID -->
@@ -52,6 +60,7 @@
 		<name>tupleid</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Generated tuple identification.</description>
 	</column>
 
 	<!-- published with this entity tag (only published tuples are stored
@@ -60,6 +69,7 @@
 		<name>etag</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Entity tag used for tuple publication.</description>
 	</column>
 
 	<!-- tuple must published with ID (see PIDF spec.) -->
@@ -67,6 +77,7 @@
 		<name>published_id</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Tuple identification used in PUBLISH.</description>
 	</column>
 
 	<index>

db/schema/presentity_extensions.xml

@@ -7,9 +7,11 @@
 
 ]>
 
-<table role="presence" xmlns:db="http://docbook.org/ns/docbook">
+<table role="presence">
 
 	<name>presentity_extensions</name>
+	<description>Table holding extension elements (non-PIDF) published directly in
+	&lt;presence&gt;.</description>
     
 	<!-- related to the version of presence snapshot -->
 	<version>5</version>
@@ -18,6 +20,7 @@
 		<name>dbid</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Generated ID used for unique identification.</description>
 	</column>
 
 	<!-- foreign key (presentity) -->
@@ -25,6 +28,7 @@
 		<name>pres_id</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Presentity ID for which is given extension element.</description>
 	</column>
 
 	<!-- received in PUBLISH with this entity tag -->
@@ -32,12 +36,14 @@
 		<name>etag</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Entity tag used for note publication.</description>
 	</column>
 
 	<!-- serialized XML element -->
 	<column>
 		<name>element</name>
 		<type>binary</type>
+		<description>Whole extension element in serialized form.</description>
 	</column>
 
 	<!-- expiration time -->
@@ -45,6 +51,8 @@
 		<name>expires</name>
 		<type>datetime</type>
 		<default>2005-12-07 08:13:15</default>
+		<description>Expiration value of extension element i.e. value of Expires
+		header used in PUBLISH.</description>
 	</column>
 
 	<index>

db/schema/presentity_notes.xml

@@ -7,9 +7,12 @@
 
 ]>
 
-<table role="presence" xmlns:db="http://docbook.org/ns/docbook">
+<table role="presence">
 
 	<name>presentity_notes</name>
+	<description>Table holding &lt;note&gt; elements published directly in
+	&lt;presence&gt; element i.e. notes related to whole presentity not only for
+	tuples.</description>
     
 	<!-- related to the version of presence snapshot -->
 	<version>5</version>
@@ -18,6 +21,7 @@
 		<name>dbid</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Generated ID used for unique identification.</description>
 	</column>
 
 	<!-- foreign key (presentity) -->
@@ -25,30 +29,36 @@
 		<name>pres_id</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Presentity ID for which is given note.</description>
 	</column>
 
 	<column>
 		<name>etag</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Entity tag used for note publication.</description>
 	</column>
 
 	<column>
 		<name>note</name>
 		<type>string</type>
 		<size>128</size>
+		<description>String value of note element.</description>
 	</column>
 
 	<column>
 		<name>lang</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Lang attribute value of note element.</description>
 	</column>
 
 	<column>
 		<name>expires</name>
 		<type>datetime</type>
 		<default>2005-12-07 08:13:15</default>
+		<description>Expiration value of note element i.e. value of Expires
+		header used in PUBLISH.</description>
 	</column>
 
 	<index>

db/schema/tuple_extensions.xml

@@ -7,30 +7,34 @@
 
 ]>
 
-<table role="presence" xmlns:db="http://docbook.org/ns/docbook">
+<table role="presence">
 
 	<name>tuple_extensions</name>
 
 	<!-- related to the version of presence snapshot -->
 	<version>5</version>
+	<description>Extension elements published within tuples.</description>
 
 	<!-- presentity ID -->
 	<column id="tuple_notes.pres_id">
 		<name>pres_id</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Presentity ID.</description>
 	</column>
 
 	<column id="tuple_notes.tupleid">
 		<name>tupleid</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Tuple identification.</description>
 	</column>
 
 	<!-- serialized XML element -->
 	<column>
 		<name>element</name>
 		<type>binary</type>
+		<description>Whole extension element in serialized form.</description>
 	</column>
 
 	<!-- 0 if it is not status extension, nonzero otherwise -->
@@ -38,6 +42,8 @@
 		<name>status_extension</name>
 		<type>int</type>
 		<size>1</size>
+		<description>Flag set to nonzero if element is nested in &lt;status&gt;,
+		otherwise is extension element nested in &lt;tuple&gt;.</description>
 	</column>
     
 </table>

db/schema/tuple_notes.xml

@@ -7,9 +7,10 @@
 
 ]>
 
-<table role="presence" xmlns:db="http://docbook.org/ns/docbook">
+<table role="presence">
 
 	<name>tuple_notes</name>
+	<description>Tuple related published notes.</description>
 
 	<!-- related to the version of presence snapshot -->
 	<version>5</version>
@@ -19,24 +20,29 @@
 		<name>pres_id</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Presentity ID.</description>
 	</column>
 
 	<column id="tuple_notes.tupleid">
 		<name>tupleid</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Tuple identification.</description>
 	</column>
 
 	<column>
 		<name>note</name>
 		<type>string</type>
 		<size>128</size>
+		<description>Note text.</description>
 	</column>
 
 	<column>
 		<name>lang</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Note language (possible note element
+		attribute).</description>
 	</column>
     
 </table>

db/schema/watcherinfo.xml

@@ -9,6 +9,8 @@
 
 <table role="presence">
     <name>watcherinfo</name>
+	<description>Table holding information about watchers. Here are both
+	presence and presence.winfo watchers.</description>
 
 	<!-- related to the version of presence snapshot -->
 	<version>5</version>
@@ -18,6 +20,8 @@
 		<name>w_uri</name>
 		<type>string</type>
 		<size>&uri_len;</size>
+		<description>Watcher's URI (From header uri used in first SUBSCRIBE
+		request).</description>
 	</column>
 
 	<!-- displayname information taken from From header -->
@@ -32,6 +36,7 @@
 		<name>s_id</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Generated watcher's identification.</description>
 	</column>
 
 	<!-- event package: presence or presence.winfo -->
@@ -40,6 +45,8 @@
 		<type>string</type>
 		<size>32</size>
 		<default>presence</default>
+		<description>Watcher's event package - presence or
+		presence.winfo.</description>
 	</column>
 
 	<column>
@@ -47,23 +54,29 @@
 		<type>string</type>
 		<size>32</size>
 		<default>pending</default>
+		<description>Watcher's status as string (pending, active,
+		rejected, terminated or pending_terminated).</description>
 	</column>
 
 	<column>
 		<name>event</name>
 		<type>string</type>
 		<size>32</size>
+		<description>Event which lead to watcher's status (subscribe,
+		...).</description>
 	</column>
 
 	<column>
 		<name>expires</name>
 		<type>datetime</type>
 		<default>2005-12-07 08:13:15</default>
+		<description>Subscription expiration value.</description>
 	</column>
 
 	<column>
 		<name>accepts</name>
 		<type>int</type>
+		<description>MIME type used in NOTIFYs.</description>
 	</column>
 
 	<!-- foreign key (presentity) -->
@@ -71,22 +84,27 @@
 		<name>pres_id</name>
 		<type>string</type>
 		<size>64</size>
+		<description>Watched presentity identification.</description>
     </column>
 
 	<column>
 		<name>server_contact</name>
 		<type>string</type>
 		<size>&uri_len;</size>
+		<description>Contact address used for resubscriptions.</description>
 	</column>
 
 	<column>
 		<name>dialog</name>
 		<type>binary</type>
+		<description>Serialized subscription dialog.</description>
 	</column>
 
 	<column>
 		<name>doc_index</name>
 		<type>int</type>
+		<description>Last index used in NOTIFY (some document formats use
+		numbers incremented in each NOTIFY).</description>
 	</column>
 
 	<index>