add descriptions and comments

src/python/bcc/table.py

@@ -440,6 +440,11 @@ def next(self, key):
  def foo(self, tmp, buckets, bucket_fn, bucket_sort_fn): #TODO: Name this function
  f1 = self.Key._fields_[0][0]
  f2 = self.Key._fields_[1][0]
+ # The above code assumes that self.Key._fields_[1][0] holds the
+ # slot. But a padding member may have been inserted here, which
+ # breaks the assumption and leads to chaos.
+ # TODO: this is a quick fix. Fixing/working around in the BCC
+ # internal library is the right thing to do.
  if f2 == '__pad_1' and len(self.Key._fields_) == 3:
  f2 = self.Key._fields_[2][0]
  for k, v in self.items():
@@ -457,6 +462,22 @@ def foo(self, tmp, buckets, bucket_fn, bucket_sort_fn): #TODO: Name this functio
 
  def print_json_hist(self, val_type="value", section_header="Bucket ptr",
  section_print_fn=None, bucket_fn=None, bucket_sort_fn=None):
+ """print_json_hist(val_type="value", section_header="Bucket ptr",
+ section_print_fn=None, bucket_fn=None,
+ bucket_sort_fn=None):
+
+ Prints a table as a json histogram. The table must be stored as
+ log2. The val_type argument is optional, and is a column header.
+ If the histogram has a secondary key, the dictionary will be split by secondary key
+ If section_print_fn is not None, it will be passed the bucket value
+ to format into a string as it sees fit. If bucket_fn is not None,
+ it will be used to produce a bucket value for the histogram keys.
+ If bucket_sort_fn is not None, it will be used to sort the buckets
+ before iterating them, and it is useful when there are multiple fields
+ in the secondary key.
+ The maximum index allowed is log2_index_max (65), which will
+ accommodate any 64-bit integer in the histogram.
+ """
  if isinstance(self.Key(), ct.Structure):
  tmp = {}
  buckets = []