counters: doc update

- document the new format used by the script_counter modparam and
  by the script functions.
- document the new cnt.help rpc.

modules/counters/README

@@ -17,9 +17,9 @@ Andrei Pelinescu-Onciul
 
    1.3. Functions
 
-        1.3.1. cnt_inc(name)
-        1.3.2. cnt_add(name, number)
-        1.3.3. cnt_reset(name)
+        1.3.1. cnt_inc([group.]name)
+        1.3.2. cnt_add([group.]name, number)
+        1.3.3. cnt_reset([group.]name)
 
    1.4. counters RPC Functions
 
@@ -28,6 +28,7 @@ Andrei Pelinescu-Onciul
         1.4.3. cnt.grps_list
         1.4.4. cnt.var_list group
         1.4.5. cnt.grp_get_all
+        1.4.6. cnt.help group counter_name
 
 1.1. Overview
 
@@ -41,17 +42,25 @@ Andrei Pelinescu-Onciul
 
 1.2.1. script_counter
 
-   Define a new counter that can be used from the script. The default
-   group name for the counter is "script" (it can be changed using the
-   script_cnt_grp_name module parameter).
+   Define a new counter that can be used from the script. The declaration
+   might include a group in front of the counter name, separated with '.'.
+   It might also include a counter description string (help message),
+   separated from the name with a ' ' or ':'. If the group is missing, the
+   group defined in the script_cnt_grp_name module parameter will be used
+   (the default is "script"). If the description is missing, the default
+   is "custom script counter". The format of the declaration is:
+   [group.]name[( |:)description].
 
    Example 1.  Create a new script_counter
-modparam("counters", "script_counter", "foo")
+modparam("counters", "script_counter", "foo")  # script.foo
+modparam("counters", "script_counter", "test.bar")  # test.bar
+modparam("counters", "script_counter", "baz example counter")  # script.baz
+modparam("counters", "script_counter", "test.x:another example") # test.x
 
 1.2.2. script_cnt_grp_name
 
-   Group name that will be used for all the counters defined via the
-   script_counter module parameter.
+   Group name that will be used for the counters defined via the
+   script_counter module parameter which do not have a specified group.
 
    Default: "script".
 
@@ -63,38 +72,44 @@ modparam("counters", "script_cnt_grp_name", "my_counters")
    Revision History
    Revision $Revision$ $Date$
 
-1.3.1.  cnt_inc(name)
+1.3.1.  cnt_inc([group.]name)
 
-   Increments the counter name. The counter must be defined using the
-   script_counter module parameter.
+   Increments the counter group.name. The counter must be defined using
+   the script_counter module parameter. If the group name is missing, the
+   group specified by the script_cnt_grp_name modparam will be used.
 
    Example 3. cnt_inc usage
 ...
 modparam("counters", "script_counter", "reqs")
+modparam("counters", "script_counter", "out.reqs  forwarded requests")
 ...
 route {
         cnt_inc("reqs");
+        if (forward(uri:host, uri:port))
+                cnt_inc("out.reqs");
 ...
 }
 
-1.3.2.  cnt_add(name, number)
+1.3.2.  cnt_add([group.]name, number)
 
-   Adds number the counter name. The counter must be defined using the
-   script_counter module parameter.
+   Adds number the counter group.name. The counter must be defined using
+   the script_counter module parameter. If the group name is missing, the
+   group specified by the script_cnt_grp_name modparam will be used.
 
    Example 4. cnt_add usage
 ...
-modparam("counters", "script_counter", "reqs10")
+modparam("counters", "script_counter", "reqs10  reqs times 10")
 ...
 route {
         cnt_add("reqs10", 10);
 ...
 }
 
-1.3.3.  cnt_reset(name)
+1.3.3.  cnt_reset([group.]name)
 
-   Resets the counter name. The counter must be defined using the
-   script_counter module parameter.
+   Resets the counter group.name. The counter must be defined using the
+   script_counter module parameter. If the group name is missing, the
+   group specified by the script_cnt_grp_name modparam will be used.
 
    Example 5. cnt_reset usage
 ...
@@ -146,3 +161,10 @@ route {
 
    Example 10. cnt.var_list group usage
  $ sercmd cnt.grp_get_all script
+
+1.4.6.  cnt.help group counter_name
+
+   Displays the counter description.
+
+   Example 11. cnt.help grp name usage
+ $ sercmd cnt.help script foo

modules/counters/doc/functions.xml

@@ -23,21 +23,26 @@
 
 	<section id="cnt_inc">
 	<title>
-		<function>cnt_inc(name)</function>
+		<function>cnt_inc([group.]name)</function>
 	</title>
 	<para>
-		Increments the counter <emphasis>name</emphasis>. The counter
+		Increments the counter <emphasis>group.name</emphasis>. The counter
 		must be defined using the <varname>script_counter</varname>
 		module parameter.
+		If the group name is missing, the group specified by the
+		<varname>script_cnt_grp_name</varname>  modparam will be used.
 	</para>
 	<example>
 		<title><function>cnt_inc</function> usage</title>
 		<programlisting>
 ...
 modparam("counters", "script_counter", "reqs")
+modparam("counters", "script_counter", "out.reqs  forwarded requests")
 ...
 route {
 	cnt_inc("reqs");
+	if (forward(uri:host, uri:port))
+		cnt_inc("out.reqs");
 ...
 }
 		</programlisting>
@@ -46,18 +51,21 @@ route {
 
 	<section id="cnt_add">
 	<title>
-		<function>cnt_add(name, number)</function>
+		<function>cnt_add([group.]name, number)</function>
 	</title>
 	<para>
-		Adds <emphasis>number</emphasis> the counter <emphasis>name</emphasis>.
+		Adds <emphasis>number</emphasis> the counter
+		<emphasis>group.name</emphasis>.
 		The counter must be defined using the
 		<varname>script_counter</varname> module parameter.
+		If the group name is missing, the group specified by the
+		<varname>script_cnt_grp_name</varname>  modparam will be used.
 	</para>
 	<example>
 		<title><function>cnt_add</function> usage</title>
 		<programlisting>
 ...
-modparam("counters", "script_counter", "reqs10")
+modparam("counters", "script_counter", "reqs10  reqs times 10")
 ...
 route {
 	cnt_add("reqs10", 10);
@@ -69,12 +77,14 @@ route {
 
 	<section id="cnt_reset">
 	<title>
-		<function>cnt_reset(name)</function>
+		<function>cnt_reset([group.]name)</function>
 	</title>
 	<para>
-		Resets the counter <emphasis>name</emphasis>. The counter
+		Resets the counter <emphasis>group.name</emphasis>. The counter
 		must be defined using the <varname>script_counter</varname>
 		module parameter.
+		If the group name is missing, the group specified by the
+		<varname>script_cnt_grp_name</varname>  modparam will be used.
 	</para>
 	<example>
 		<title><function>cnt_reset</function> usage</title>

modules/counters/doc/params.xml

@@ -22,16 +22,26 @@
 		<title><varname>script_counter</varname></title>
 		<para>
 			Define a new counter that can be used from the script.
-			The default group name for the counter is "script"
-			(it can be changed using the
-			<varname>script_cnt_grp_name</varname> module parameter).
+			The declaration might include a group in front of the counter
+			name, separated with '.'. It might also include a counter
+			description string (help message), separated from the name
+			with a ' ' or  ':'.
+			If the group is missing, the group defined in the
+			<varname>script_cnt_grp_name</varname> module parameter will
+			be used (the default is "script").
+			If the description is missing, the default is
+			"custom script counter".
+			The format of the declaration is: [group.]name[( |:)description].
 		</para>
 		<example>
 			<title>
 				Create a new <varname>script_counter</varname>
 			</title>
 			<programlisting>
-modparam("counters", "script_counter", "foo")
+modparam("counters", "script_counter", "foo")  # script.foo
+modparam("counters", "script_counter", "test.bar")  # test.bar
+modparam("counters", "script_counter", "baz example counter")  # script.baz
+modparam("counters", "script_counter", "test.x:another example") # test.x
 			</programlisting>
 		</example>
 	</section>
@@ -39,8 +49,9 @@ modparam("counters", "script_counter", "foo")
 	<section id="scrip_cnt_grp_name">
 		<title><varname>script_cnt_grp_name</varname></title>
 		<para>
-			Group name that will be used for all the counters defined
-			via the <varname>script_counter</varname> module parameter.
+			Group name that will be used for the counters defined
+			via the <varname>script_counter</varname> module parameter which
+			do not have a specified group.
 		</para>
 		<para>
 			Default: "script".

modules/counters/doc/rpc.xml

@@ -85,5 +85,18 @@
 		</example>
 	</section>
 
+	<section id="cnt.help">
+		<title> <function>cnt.help group counter_name</function></title>
+		<para>
+			Displays the counter description.
+		</para>
+		<example>
+			<title><function>cnt.help grp name</function> usage</title>
+			<programlisting>
+ $ &sercmd; cnt.help script foo
+			</programlisting>
+		</example>
+	</section>
+
 
 </section>