improved the developer documentation

* tvb_*_length mentioned in README.dissector
* fixed typos in README.dissector
* using stats_tree_register_plugin in the stats_tree examples both in README.stats_tree and the dev guide
* removed the version information and the #endif from the stats tree section in README.dissector

Change-Id: I27df0b5dfd66a7c0ac5b0fe1bdc882b3e9ffda74
Reviewed-on: https://code.wireshark.org/review/12908
Reviewed-by: Alexis La Goutte <alexis.lagoutte@gmail.com>
Petri-Dish: Alexis La Goutte <alexis.lagoutte@gmail.com>
Reviewed-by: Michael Mann <mmann78@netscape.net>

4 files changed, 43 insertions, 27 deletions

diff --git a/AUTHORS b/AUTHORS
index c24a129228..f069103312 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -3669,6 +3669,10 @@ Guillaume Autran	<gautran[AT]clearpathrobotics.com> {
 	TCPROS support
 }
 
+Barbu Paul - Gheorghe	<barbu.paul.gheorghe[AT]gmail.com> {
+	Developer documentation improvements
+}
+
 
 and by:
 
diff --git a/doc/README.dissector b/doc/README.dissector
index 6753483e75..197a985253 100644
--- a/doc/README.dissector
+++ b/doc/README.dissector
@@ -41,6 +41,7 @@ Laurent Deniel <laurent.deniel[AT]free.fr>
 Gerald Combs <gerald[AT]wireshark.org>
 Guy Harris <guy[AT]alum.mit.edu>
 Ulf Lamping <ulf.lamping[AT]web.de>
+Barbu Paul - Gheorghe <barbu.paul.gheorghe[AT]gmail.com>
 
 1. Setting up your protocol dissector code.
 
@@ -405,6 +406,16 @@ Pointer-retrieval:
  */
 guint8* tvb_get_ptr(tvbuff_t *tvb, gint offset, gint length);
 
+Length query:
+Get amount of captured data in the buffer (which is *NOT* necessarily the
+length of the packet). You probably want tvb_reported_length instead:
+
+    guint tvb_captured_length(const tvbuff_t *tvb);
+
+Get reported length of buffer:
+
+    guint tvb_reported_length(const tvbuff_t *tvb);
+
 
 1.4 Functions to handle columns in the traffic summary window.
 
@@ -2695,7 +2706,7 @@ upon the conversation index and values inside the request packets.
 NOTE:   This sections assumes that all information is available to
     create a complete conversation, source port/address and
     destination port/address.  If either the destination port or
-    address is know, see section 2.4 Dynamic server port dissector
+    address is known, see section 2.4 Dynamic server port dissector
     registration.
 
 For protocols that negotiate a secondary port connection, for example
diff --git a/doc/README.stats_tree b/doc/README.stats_tree
index 4a126723b2..8f62778d93 100644
--- a/doc/README.stats_tree
+++ b/doc/README.stats_tree
@@ -17,11 +17,11 @@ The init callback routine:
    which will be executed before any packet is passed to the tap. Here you
    should create the "static" nodes of your tree. As well as initialize your
    data.
-   
+
 The (per)packet callback routine:
    As the tap_packet callback is going to be called for every packet, it
    should be used to increment the counters.
-   
+
 The cleanup callback:
    It is called at the destruction of the stats_tree and might be used to
    free ....
@@ -79,21 +79,21 @@ static gchar* st_str_udp_term = "UDP terminations";
 /* this one initializes the tree, creating the root nodes */
 extern void udp_term_stats_tree_init(stats_tree* st) {
 	/* we create a node under which we'll add every termination */
-	st_udp_term = stats_tree_create_node(st, st_str_udp_term, 0, TRUE);	
+	st_udp_term = stats_tree_create_node(st, st_str_udp_term, 0, TRUE);
 }
 
 /* this one will be called with every udp packet */
-extern int udp_term_stats_tree_packet(stats_tree *st, /* st as it was passed to us */ 
+extern int udp_term_stats_tree_packet(stats_tree *st, /* st as it was passed to us */
                                       packet_info *pinfo,  /* we'll fetch the addresses from here */
-                                      epan_dissect_t *edt _U_, /* unused */ 
+                                      epan_dissect_t *edt _U_, /* unused */
                                       const void *p) /* we'll use this to fetch the ports */
 {
 	static guint8 str[128];
 	e_udphdr* udphdr = (e_udphdr*) p;
-	
+
 	/* we increment by one (tick) the root node */
 	tick_stat_node(st, st_str_udp_term, 0, FALSE);
-	
+
 	/* we then tick a node for this src_addr:src_port
 	   if the node doesn't exists it will be created */
 	g_snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_src),udphdr->sport);
@@ -102,7 +102,7 @@ extern int udp_term_stats_tree_packet(stats_tree *st, /* st as it was passed to
 	/* same thing for dst */
 	g_snprintf(str, sizeof(str),"%s:%u",address_to_str(&pinfo->net_dst),udphdr->dport);
 	tick_stat_node(st, str, st_udp_term, FALSE);
-	
+
 	return 1;
 }
 
@@ -111,13 +111,13 @@ WS_DLL_PUBLIC_DEF const gchar version[] = "0.0";
 
 WS_DLL_PUBLIC_DEF void plugin_register_tap_listener(void) {
 
-    stats_tree_register("udp", /* the proto we are going to "tap" */
-                        "udp_terms", /* the abbreviation for this tree (to be used as -z udp_terms,tree) */
-                        st_str_udp_term, /* the name of the menu and window (use "/" for sub menus)*/
-                        0, /* tap listener flags for per-packet callback */
-                        udp_term_stats_tree_packet, /* the per packet callback */
-                        udp_term_stats_tree_init, /* the init callback */
-                        NULL ); /* the cleanup callback (in this case there isn't) */
+    stats_tree_register_plugin("udp", /* the proto we are going to "tap" */
+                               "udp_terms", /* the abbreviation for this tree (to be used as -z udp_terms,tree) */
+                               st_str_udp_term, /* the name of the menu and window (use "/" for sub menus)*/
+                               0, /* tap listener flags for per-packet callback */
+                               udp_term_stats_tree_packet, /* the per packet callback */
+                               udp_term_stats_tree_init, /* the init callback */
+                               NULL ); /* the cleanup callback (in this case there isn't) */
 
 }
 #endif
@@ -132,8 +132,11 @@ the stats_tree API
 stats_tree_register( tapname, abbr, name, flags, packet_cb, init_cb, cleanup_cb);
  registers a new stats tree
 
+stats_tree_register_plugin(tapname, abbr, name, flags, packet_cb, init_cb, cleanup_cb);
+ registers a new stats tree from a plugin
+
 stats_tree_parent_id_by_name( st, parent_name)
-  returns the id of a candidate parent node given its name 
+  returns the id of a candidate parent node given its name
 
 
 Node functions
@@ -192,7 +195,7 @@ resets to zero a stat_node
 Averages work by tracking both the number of items added to node (the ticking
 action) and the value of each item added to the node. This is done
 automatically for ranged nodes; for other node types you need to call one of
-the functions below to associate item values with each tick. 
+the functions below to associate item values with each tick.
 
 avg_stat_node_add_value_notick(st,name,parent_id,with_children,value)
 avg_stat_node_add_value(st,name,parent_id,with_children,value)
@@ -214,10 +217,10 @@ with avg_stat_node_add_value as this will lead to incorrect results for the
 average value.
 
 stats_tree now also support setting flags per node to control the behaviour
-of these nodes. This can be done using the stat_node_set_flags and 
+of these nodes. This can be done using the stat_node_set_flags and
 stat_node_clear_flags functions. Currently these flags are defined:
 
-	ST_FLG_DEF_NOEXPAND: By default the top-level nodes in a tree are 
+	ST_FLG_DEF_NOEXPAND: By default the top-level nodes in a tree are
 			automatically expanded in the GUI. Setting this flag on
 			such a node	prevents the node from automatically expanding.
 	ST_FLG_SORT_TOP: Nodes with this flag is sorted separately from nodes
diff --git a/docbook/wsdg_src/WSDG_chapter_dissection.asciidoc b/docbook/wsdg_src/WSDG_chapter_dissection.asciidoc
index 84b05240bd..f81f1eebed 100644
--- a/docbook/wsdg_src/WSDG_chapter_dissection.asciidoc
+++ b/docbook/wsdg_src/WSDG_chapter_dissection.asciidoc
@@ -1060,18 +1060,14 @@ Here is a mechanism to produce statistics from the above TAP interface.
 ----
 /* register all http trees */
 static void register_foo_stat_trees(void) {
-    stats_tree_register("foo", "foo", "Foo/Packet Types",
+    stats_tree_register_plugin("foo", "foo", "Foo/Packet Types", 0,
         foo_stats_tree_packet, foo_stats_tree_init, NULL);
 }
 
-WS_DLL_PUBLIC_DEF const gchar version[] = "0.0";
-
 WS_DLL_PUBLIC_DEF void plugin_register_tap_listener(void)
 {
     register_foo_stat_trees();
 }
-
-#endif
 ----
 ====
 
@@ -1079,8 +1075,8 @@ Working from the bottom up, first the plugin interface entry point is defined,
 +plugin_register_tap_listener()+. This simply calls the initialisation function
 +register_foo_stat_trees()+.
 
-This in turn calls the +stats_tree_register()+ function, which takes three
-strings, and three functions.
+This in turn calls the +stats_tree_register_plugin()+ function, which takes three
+strings, an integer, and three callback functions.
 
 . This is the tap name that is registered.
 
@@ -1088,6 +1084,8 @@ strings, and three functions.
 
 . The name of the stats module. A $$'/'$$ character can be used to make sub menus.
 
+. Flags for per-packet callback
+
 . The function that will called to generate the stats.
 
 . A function that can be called to initialise the stats data.