[2298] update the docstring of item_name_list()

diff --git a/src/bin/stats/stats_httpd.py.in b/src/bin/stats/stats_httpd.py.in
index b756d4dd31f2d36d0f7a6e63f57c4b7d4978ce1c..4b19111a3a408295c3eca18210e00f584623cfd8 100644 (file)
--- a/src/bin/stats/stats_httpd.py.in
+++ b/src/bin/stats/stats_httpd.py.in
@@ -73,10 +73,37 @@ XSD_NAMESPACE = 'http://bind10.isc.org/bind10'
 isc.util.process.rename()
 
 def item_name_list(element, identifier):
-    """Returns list of items. The first argument elemet is dict-type
-    value to traverse, the second argument is a string separated
-    '/'. This is a start porint to traverse. At the end in the
-    method. The list to be returned is sorted. """
+    """Return a list of strings. The strings are string expression of
+    the first argument element which is dict type. The second argument
+    identifier is a string for specifying the strings which are
+    returned from this method as a list. For example, if we specify as
+
+      item_name_list({'a': {'aa': [0, 1]}, 'b': [0, 1]}, 'a/aa'),
+
+    then it returns
+
+      ['a/aa', 'a/aa[0]', 'a/aa[1]'].
+
+    If an empty string is specified in the second argument, all
+    possible strings are returned as a list.  In that example if we
+    specify an empty string in the second argument, then it returns
+
+      ['a', 'a/aa', 'a/aa[0]', 'a/aa[1]', 'b', 'b[0]', 'b[1]'].
+
+    The key name of element which is in the first argument is sorted.
+    Even if we specify as
+
+      item_name_list({'xx': 0, 'a': 1, 'x': 2}, ''),
+
+    then it returns
+
+      ['a', 'x', 'xx'].
+
+    This method internally invokes isc.cc.data.find(). The arguments
+    of this method are passed to isc.cc.data.find(). So an exception
+    DataNotFoundError or DataTypeError might be raised via
+    isc.cc.data.find() depending on the arguments. See details of
+    isc.cc.data.find() for more information about exceptions"""
     elem = isc.cc.data.find(element, identifier)
     ret = []
     ident = identifier