"Highly discourage" use of proto_tree_add_text.

Change-Id: I2e8d18df71688c654f7acaff51fae7823c08aa6a
Reviewed-on: https://code.wireshark.org/review/3677
Reviewed-by: Michael Mann <mmann78@netscape.net>
Petri-Dish: Michael Mann <mmann78@netscape.net>
Tested-by: Petri Dish Buildbot <buildbot-no-reply@wireshark.org>
Reviewed-by: Jeff Morriss <jeff.morriss.ws@gmail.com>
Reviewed-by: Evan Huus <eapache@gmail.com>

doc/README.dissector

@@ -1092,10 +1092,10 @@ protocol or field labels to the proto_tree:
     proto_tree_add_item(tree, id, tvb, start, length, encoding);
 
     proto_item*
-    proto_tree_add_text(tree, tvb, start, length, format, ...);
+    proto_tree_add_subtree(tree, tvb, start, length, label);
 
     proto_item*
-    proto_tree_add_text_valist(tree, tvb, start, length, format, ap);
+    proto_tree_add_subtree_format(tree, tvb, start, length, format, ...);
 
     proto_item*
     proto_tree_add_none_format(tree, id, tvb, start, length, format, ...);
@@ -1688,16 +1688,14 @@ With these routines, unlike the proto_tree_add_XXX_format() routines,
 the name of the field is added automatically as in the
 proto_tree_add_XXX() functions; only the value is added with the format.
 
-proto_tree_add_text()
+proto_tree_add_subtree()
 ---------------------
-proto_tree_add_text() is used to add a label to the GUI tree.  It will
-contain no value, so it is not searchable in the display filter process.
+proto_tree_add_subtree() is used to add a label to the GUI tree and create
+a subtree for other fields.  It will contain no value, so it is not searchable
+in the display filter process.
 
-This can (and should only) be used for items with subtrees, which may not
+This should only be used for items with subtrees, which may not
 have values themselves - the items in the subtree are the ones with values.
-In other words, if you're using proto_tree_add_text() and not using the
-return value to build a new tree, you probably shouldn't be using this
-function: you probably should be using proto_tree_add_item() instead.
 
 For a subtree, the label on the subtree might reflect some of the items
 in the subtree.  This means the label can't be set until at least some
@@ -1710,10 +1708,10 @@ of the items in the subtree have been dissected.  To do this, use
     void
     proto_item_append_text(proto_item *ti, ...);
 
-'proto_item_set_text()' takes as an argument the value returned by
-'proto_tree_add_text()', a 'printf'-style format string, and a set of
-arguments corresponding to '%' format items in that string, and replaces
-the text for the item created by 'proto_tree_add_text()' with the result
+'proto_item_set_text()' takes as an argument the proto_item value returned by
+one of the parameters in 'proto_tree_add_subtree()', a 'printf'-style format
+string, and a set of arguments corresponding to '%' format items in that string,
+and replaces the text for the item created by 'proto_tree_add_subtree()' with the result
 of applying the arguments to the format string.
 
 'proto_item_append_text()' is similar, but it appends to the text for
@@ -1721,7 +1719,7 @@ the item the result of applying the arguments to the format string.
 
 For example, early in the dissection, one might do:
 
-    ti = proto_tree_add_text(tree, tvb, offset, length, <label>);
+    subtree = proto_tree_add_subtree(tree, tvb, offset, length, ett, &ti, <label>);
 
 and later do
 
@@ -1737,10 +1735,10 @@ available.  Thus, one should create the item with text that is as
 meaningful as possible, and set it or append additional information to
 it as the values needed to supply that information are extracted.
 
-proto_tree_add_text_valist()
+proto_tree_add_subtree_format()
 ----------------------------
-This is like proto_tree_add_text(), but takes, as the last argument, a
-'va_list'; it is used to allow routines that take a printf-like
+This is like proto_tree_add_subtree(), but uses printf-style arguments to
+create the label; it is used to allow routines that take a printf-like
 variable-length list of arguments to add a text item to the protocol
 tree.
 

epan/proto.c

@@ -1082,7 +1082,7 @@ proto_tree_add_text_node(proto_tree *tree, tvbuff_t *tvb, gint start, gint lengt
 	return pi;
 }
 
-/* Add a text-only node to the proto_tree */
+/* (DEPRECATED) Add a text-only node to the proto_tree */
 proto_item *
 proto_tree_add_text(proto_tree *tree, tvbuff_t *tvb, gint start, gint length,
 		    const char *format, ...)
@@ -1104,7 +1104,7 @@ proto_tree_add_text(proto_tree *tree, tvbuff_t *tvb, gint start, gint length,
 	return pi;
 }
 
-/* Add a text-only node to the proto_tree (va_list version) */
+/* (DEPRECATED) Add a text-only node to the proto_tree (va_list version) */
 proto_item *
 proto_tree_add_text_valist(proto_tree *tree, tvbuff_t *tvb, gint start,
 			   gint length, const char *format, va_list ap)

epan/proto.h

@@ -900,7 +900,7 @@ WS_DLL_PUBLIC proto_item *
 proto_tree_add_item(proto_tree *tree, int hfindex, tvbuff_t *tvb,
 		    const gint start, gint length, const guint encoding);
 
-/** Add a text-only node to a proto_tree.
+/** (DEPRECATED) Add a text-only node to a proto_tree.
  @param tree the tree to append this item to
  @param tvb the tv buffer of the current data
  @param start start of data in tvb
@@ -912,7 +912,7 @@ WS_DLL_PUBLIC proto_item *
 proto_tree_add_text(proto_tree *tree, tvbuff_t *tvb, gint start, gint length, const char *format,
 	...) G_GNUC_PRINTF(5,6);
 
-/** Add a text-only node to a proto_tree using a variable argument list.
+/** (DEPRECATED) Add a text-only node to a proto_tree using a variable argument list.
  @param tree the tree to append this item to
  @param tvb the tv buffer of the current data
  @param start start of data in tvb

tools/checkAPIs.pl

@@ -135,6 +135,8 @@ my %APIs = (
                 'tvb_ensure_length_remaining', # replaced with tvb_ensure_captured_length_remaining
                 'tvb_get_string', # replaced with tvb_get_string_enc
                 'tvb_get_stringz', # replaced with tvb_get_stringz_enc
+                'proto_tree_add_text', # replaced with proto_tree_add_subtree[_format], expert_add_info[_format], or proto_tree_add_expert[_format]
+                'proto_tree_add_text_valist', # replaced with proto_tree_add_subtree_format, expert_add_info_format, or proto_tree_add_expert_format
 
                 # wmem calls should replace all emem calls (see doc/README.wmem)
                 'ep_alloc',
@@ -1386,7 +1388,7 @@ sub checkAddTextCalls($$)
         my $okay_add_text_count = 0;
         my $add_xxx_count = 0;
         my $total_count = 0;
-        my $aggressive = 0;
+        my $aggressive = 1;
         my $percentage = 100;
 
         # The 3 loops here are slow, but trying a single loop with capturing