git:andrei/counters: counters: doc update - sr-dev

9 Aug 2010

Module: sip-router
Branch: andrei/counters
Commit: 0c5cadddd86c31ce8021811ad4806c02200e21ce
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=0c5caddd...
Author: Andrei Pelinescu-Onciul andrei@iptel.org
Committer: Andrei Pelinescu-Onciul andrei@iptel.org
Date:   Mon Aug  9 17:41:25 2010 +0200
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            |   60 ++++++++++++++++++++++++-----------
 modules/counters/doc/functions.xml |   24 ++++++++++----
 modules/counters/doc/params.xml    |   23 ++++++++++---
 modules/counters/doc/rpc.xml       |   13 ++++++++
 4 files changed, 88 insertions(+), 32 deletions(-)

diff --git a/modules/counters/README b/modules/counters/README
index 025f400..59b3fc6 100644
--- a/modules/counters/README
+++ b/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
diff --git a/modules/counters/doc/functions.xml b/modules/counters/doc/functions.xml
index 0138e68..a004872 100644
--- a/modules/counters/doc/functions.xml
+++ b/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>
diff --git a/modules/counters/doc/params.xml b/modules/counters/doc/params.xml
index 52c1ba9..e8b1510 100644
--- a/modules/counters/doc/params.xml
+++ b/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".
diff --git a/modules/counters/doc/rpc.xml b/modules/counters/doc/rpc.xml
index 9782ce0..a01e6bb 100644
--- a/modules/counters/doc/rpc.xml
+++ b/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>

    