db_redis: Some minor changes to documentation for more idiomatic English and additional clarity.

src/modules/db_redis/doc/db_redis.xml

@@ -22,6 +22,11 @@
 		<surname>Granig</surname>
 		<email>[email protected]</email>
 	    </editor>
+	    <editor>
+		<firstname>Alex</firstname>
+		<surname>Balashov</surname>
+		<email>[email protected]</email>
+	    </editor>
 	</authorgroup>
 	<copyright>
 	    <year>2018</year>

src/modules/db_redis/doc/db_redis_admin.xml

@@ -14,49 +14,53 @@
 	<section>
 		<title>Overview</title>
 		<para>
-			This module provides a DB APIv1 connector for Redis server.
+			This module provides a DB APIv1 connector for the Redis server (<ulink url="https://www.redis.io">https://www.redis.io</ulink>).
+
 		</para>
 		<para>
 			It can be used as a replacement for other database modules such as
 			db_mysql and db_postgres. Not all the specs of DB APIv1 are
 			implemented, thus the usage of this module might be restricted to
-			specific modules. Also, for proper performance, the module needs
-			particular configuration tailored to the using modules.
+			specific modules. Also, for proper performance, this module needs
+			particular configuration tailored to the modules that make use of it.
 		</para>
 		<para>
 			Since Redis does not provide a schema by itself, db_redis ships with
-			schema files, which path has to be defined as module parameter "schema_path".
-			The schema definition is defined in one file per table with the file name
-			being the table name, and each file is composed of a
-			comma-separated list of column definitions in format
+			schema files. The path to these has to be defined using the module parameter 
+			"schema_path". The schema definition is defined in one file per table, such that 
+			the file name corresponds to the table name, and each file is composed of a
+			comma-separated list of column definitions in the format
 			&lt;column-name&gt;/&lt;type&gt;[,&lt;column-name&gt;/&lt;type&gt; ...]
 			in one line, followed by a line holding the table version.
 		</para>
 		<para>
-			Example for location definition:
+			Example definition for the "location" table (from the usrloc module):
 			<programlisting format="linespecific">
 username/string,domain/string,contact/string,received/string,path/string,expires/timestamp,q/double,callid/string,cseq/int,last_modified/timestamp,flags/int,cflags/int,user_agent/string,socket/string,methods/int,ruid/string,reg_id/int,instance/string,server_id/int,connection_id/int,keepalive/int,partition/int
 8
 			</programlisting>
 		</para>
 		<para>
-			Also since Redis is a key-value store with keys having to be unique,
-			tables and rows e.g. from MySQL can not be ported 1:1 to Redis. For
-			instance, usrloc relies on a key "username@domain", but it must not be
-			unique for being able to store multiple contacts per AoR. Thus, db_redis
-			supports mapping sets in a way for example for usrloc to have a set with
-			a key "username@domain", with its entries being unique keys per contact being
-			the ruid of a contact. Thus, one contact in usrloc consists of a unique
-			key "location:entry::example-ruid-1" being a hash with the columns like
+			Because Redis is a key-value store, it requires unique keys. This means
+			that tables and rows from a relational SQL database, e.g. from MySQL, can 
+			not be ported one a 1:1 basis to Redis.
+		</para>
+		<para>
+			For instance, usrloc relies on a key of "username@domain", but in order to store
+			multiple contacts per AoR, it cannot be constrained to uniqueness. To 
+			work around this, db_redis supports mapping sets in such a way as to, in the case of
+			the usrloc module, have a set with a key of "username@domain" and its entries being 
+			unique keys per contact based on the ruid of a contact. Thus, one contact in usrloc 
+			consists of a unique key "location:entry::example-ruid-1" being a hash with the columns like
 			username, domain, contact, path etc. In addition, this unique key is stored
 			in a set "location:usrdom::exampleuser:exampledomain.org". When usrloc does
 			a lookup based on "username@domain", db_redis figures out via the keys/values
-			the query is constructed by usrloc to look for the final entry key in the
-			mapping set first, then querying the actual entries from there, avoiding full
+			the query constructed by usrloc to look for the final entry key in the
+			mapping set first. It then query the actual entries from there, avoiding full
 			table scans. For usrloc, the same holds true for expired contacts, requiring
 			a different kind of mapping. There is a certain balance of read performance
 			vs. write performance to consider, because inserts and deletes also have to
-			maintain the mappings, in favor of much faster selects. The mappings can be
+			maintain the mappings, though this yields much faster selects. The mappings can be
 			freely defined, so even though other kamailio modules don't require a specific
 			mapping to be in place for proper performance, mappings could be defined
 			for external applications to read faster (for instance letting the acc module
@@ -64,8 +68,8 @@ username/string,domain/string,contact/string,received/string,path/string,expires
 			correlate start and stop records faster).
 		</para>
 		<para>
-			The mappings can be freely defined in the "keys" module parameter. It is
-			composed of a semi-colon separated list of definitions in format
+			The mappings can be freely defined in the "keys" module parameter, which is
+			composed of a semi-colon separated list of definitions in the format
 			&lt;table-name&gt;=&lt;entry&gt;:&lt;column-name&gt;[&amp;&lt;map-name&gt;:&lt;column-name&gt;,&lt;column-name&gt;...].
 			Each table must at least have an "entry" key for db_redis to be able to store data.
 		</para>
@@ -76,12 +80,8 @@ location=entry:ruid&amp;usrdom:username,domain&amp;timer:partition,keepalive;acc
 			</programlisting>
 		</para>
 		<para>
-			For readability purposes, keys per table can be defined line by line by
-			providing multiple "keys" mod-params.
-		</para>
-		<para>
-			You can read more about Redis at:
-			<ulink url="https://www.redis.io">https://www.redis.io</ulink>.
+			For readability purposes, definitions of keys per table can span multiple Kamailio 
+			config lines by providing multiple "keys" modparams.
 		</para>
 	</section>
 
@@ -90,10 +90,10 @@ location=entry:ruid&amp;usrdom:username,domain&amp;timer:partition,keepalive;acc
 		<itemizedlist>
 			<listitem>
 				<para>
-					This module has implemented the equivalent operations for INSERT,
-					UPDATE, DELETE and SELECT. The ORDER BY for SELECT is not implemented.
-					Raw query is not implemented inside this module, use ndb_redis for sending any
-					kind of command to a Redis server.
+					This module has implemented equivalent underlying Redis operations for INSERT,
+					UPDATE, DELETE and SELECT. The ORDER BY clause for SELECT is not implemented.
+					Raw querying is not implemented inside this module; for sending literal commands
+					to the Redis server, use ndb_redis. 
 				</para>
 			</listitem>
 		</itemizedlist>
@@ -121,7 +121,7 @@ location=entry:ruid&amp;usrdom:username,domain&amp;timer:partition,keepalive;acc
 		<section>
 			<title><varname>schema_path</varname> (string)</title>
 			<para>
-				The path to the schema of your tables (default /usr/share/kamailio/db_redis).
+				The path to the table schemas (default /usr/share/kamailio/db_redis).
 			</para>
 			<example>
 				<title>Setting schema_path module parameter</title>
@@ -134,7 +134,7 @@ modparam("db_redis", "schema_path", "/usr/local/share/kamailio/db_redis/kamailio
 		<section>
 			<title><varname>keys</varname> (string)</title>
 			<para>
-				The entry and mapping keys of your tables.
+				The entry and mapping keys of tables.
 			</para>
 			<example>
 				<title>Setting keys module parameter</title>
@@ -164,9 +164,9 @@ modparam("db_redis", "keys", "version=entry:table_name;location=entry:ruid&amp;u
 	<section>
 		<title>Usage</title>
 		<para>
-			Load the module and set the the DB URL for specific modules to:
+			Load the module and set the "db_url" modparam for specific modules to:
 			redis://[username]@host:port/database. Username is optional.
-			Database must be a valid redis database number.
+			The database portion must be a valid Redis database number.
 		</para>
 		<example>
 			<title>Usage</title>