From: Naoki Kambe <kambe@jprs.co.jp>
Date: Tue, 30 Oct 2012 09:00:44 +0000 (+0900)
Subject: [2298] update the docstring of item_name_list()
X-Git-Tag: trac2487_base~1^2~27^2~5
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=5fdb1fac02d282ee35f364313ea666ba34812972;p=thirdparty%2Fkea.git

[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 b756d4dd31..4b19111a3a 100644
--- 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