[SCM] archer-pmuldoon-python-backtrace: Add comments, and clarify other comments

[SCM] archer-pmuldoon-python-backtrace: Add comments, and clarify other comments

[pmuldoon]

The branch, archer-pmuldoon-python-backtrace has been updated
       via  29c6fb0276468dd53fd6b418e9e406173699413c (commit)
      from  d39df4354f1b9037bc4879ad66f1aebb3181c50b (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email.

- Log -----------------------------------------------------------------
commit 29c6fb0276468dd53fd6b418e9e406173699413c
Author: Phil Muldoon <pmuldoon@redhat.com>
Date:   Tue Feb 26 11:48:03 2013 +0000

    Add comments, and clarify other comments

-----------------------------------------------------------------------

Summary of changes:
 gdb/python/lib/gdb/command/frame_filters.py |   93 +++++++++++++++++----------
 gdb/python/lib/gdb/frames.py                |   33 +++++++---
 2 files changed, 81 insertions(+), 45 deletions(-)

First 500 lines of diff:
diff --git a/gdb/python/lib/gdb/command/frame_filters.py b/gdb/python/lib/gdb/command/frame_filters.py
index 01df066..f5d5f1d 100644
--- a/gdb/python/lib/gdb/command/frame_filters.py
+++ b/gdb/python/lib/gdb/command/frame_filters.py
@@ -43,15 +43,19 @@ def _parse_arg(cmd_name, arg):
 
 def _get_priority(filter_item):
     """ Internal worker function to return the frame-filter's priority
-    from a frame filter tuple object.
+    from a frame filter object.  This is a fail free function as it is
+    used in sorting and filtering.  If a badly implemented frame
+    filter does not implement the priority attribute, return zero
+    (otherwise sorting/filtering will fail and prevent other frame
+    filters from executing).
 
     Arguments:
-        filter_item: A tuple, with the first element being the name,
-                     and the second being the frame-filter object.
+        filter_item: An object conforming to the frame filter
+                     interface.
 
     Returns:
         The priority of the frame filter from the "priority"
-        attribute.
+        attribute, or zero.
     """
     # Do not fail here, as the sort will fail.  If a filter has not
     # (incorrectly) set a priority, set it to zero.
@@ -67,17 +71,17 @@ def _set_priority(filter_item, priority):
         filter_item: An object conforming to the frame filter
                      interface.
         priority: The priority to assign as an integer.
-
-    Raises:
-        gdb.GdbError: When the priority attribute has not been
-                      implemented.
     """
 
     filter_item.priority = priority
 
 def _get_enabled(filter_item):
-    """ Internal worker function to return the frame-filter's enabled
-    state.
+    """ Internal worker function to return a filter's enabled state
+    from a frame filter object.  This is a fail free function as it is
+    used in sorting and filtering.  If a badly implemented frame
+    filter does not implement the enabled attribute, return False
+    (otherwise sorting/filtering will fail and prevent other frame
+    filters from executing).
 
     Arguments:
         filter_item: An object conforming to the frame filter
@@ -85,11 +89,7 @@ def _get_enabled(filter_item):
 
     Returns:
         The enabled state of the frame filter from the "enabled"
-        attribute.
-
-    Raises:
-        gdb.GdbError: When the enabled attribute has not been
-                      implemented.
+        attribute, or False.
     """
 
     # If the filter class is badly implemented when called from the
@@ -108,10 +108,6 @@ def _set_enabled(filter_item, state):
         filter_item: An object conforming to the frame filter
                      interface.
         state: True or False, depending on desired state.
-
-    Raises:
-        gdb.GdbError: When the enabled attribute has not been
-                      implemented.
     """
 
     filter_item.enabled = state
@@ -128,8 +124,8 @@ def _get_name(frame_filter):
         The name of the frame filter from the "name" attribute.
 
     Raises:
-        gdb.GdbError: When the name attribute has not been
-                      implemented.
+        AttributeError: When the name attribute has not been
+        implemented.
     """
     return frame_filter.name
 
@@ -199,8 +195,8 @@ class InfoFrameFilter(gdb.Command):
         in a dictionary.
 
         Arguments:
-            frame_filters: The name of the dictionary, as
-                           specified by GDB user commands.
+           frame_filters: The name of the dictionary, as
+           specified by GDB user commands.
         """
 
         sorted_frame_filters = sorted (frame_filters.items(),
@@ -265,8 +261,18 @@ def _do_enable_frame_filter(command_tuple, flag):
 
     _set_enabled(ff, flag)
 
-def _complete_frame_filter_list (text,word):
+def _complete_frame_filter_list (text, word):
+    """Worker for frame filter dictionary name completion.
 
+    Arguments:
+        text: The full text of the command line.
+        word: The most recent word of the command line.
+
+    Returns:
+        A list of suggested frame filter dictionary name completions
+        from text/word analysis.  This list can be empty when there
+        are no suggestions for completion.
+    """
     filter_locations = ["global","progspace"]
     for objfile in gdb.objfiles():
         filter_locations.append(objfile.filename)
@@ -277,6 +283,7 @@ def _complete_frame_filter_list (text,word):
     if (text == ""):
         return filter_locations
 
+    # Otherwise filter on what we know.
     flist = filter(lambda x,y=text:x.startswith(y), filter_locations)
 
     # If we only have one completion, complete it and return it.
@@ -287,9 +294,22 @@ def _complete_frame_filter_list (text,word):
     # dictioanries that the previous filter operation returned.
     return flist
 
-def _complete_frame_filter_name (word, printer_list):
+def _complete_frame_filter_name (word, printer_dict):
+    """Worker for frame filter name completion.
+
+    Arguments:
+
+        word: The most recent word of the command line.
+
+        printer_dict: The frame filter dictionary to search for frame
+        filter name completions.
 
-    printer_keys = printer_list.keys()
+        Returns: A list of suggested frame filter name completions
+        from word analysis of the frame filter dictionary.  This list
+        can be empty when there are no suggestions for completion.
+    """
+
+    printer_keys = printer_dict.keys()
     if (word == ""):
         return printer_keys
 
@@ -313,6 +333,8 @@ class EnableFrameFilter(gdb.Command):
         super(EnableFrameFilter, self).__init__("enable frame-filter",
                                                  gdb.COMMAND_DATA)
     def complete (self,text,word):
+        """Completion function for both frame filter dictionary, and
+        frame filter name."""
         if text.count(" ") == 0:
             return _complete_frame_filter_list(text,word)
         else:
@@ -320,7 +342,6 @@ class EnableFrameFilter(gdb.Command):
             return _complete_frame_filter_name(word, printer_list)
 
     def invoke(self, arg, from_tty):
-        """GDB calls this to perform the command."""
         command_tuple = _parse_arg("enable frame-filter", arg)
         _do_enable_frame_filter(command_tuple, True)
 
@@ -343,6 +364,8 @@ class DisableFrameFilter(gdb.Command):
                                                   gdb.COMMAND_DATA)
 
     def complete (self,text,word):
+        """Completion function for both frame filter dictionary, and
+        frame filter name."""
         if text.count(" ") == 0:
             return _complete_frame_filter_list(text,word)
         else:
@@ -350,7 +373,6 @@ class DisableFrameFilter(gdb.Command):
             return _complete_frame_filter_name(word, printer_list)
 
     def invoke(self, arg, from_tty):
-        """GDB calls this to perform the command."""
         command_tuple = _parse_arg("disable frame-filter", arg)
         _do_enable_frame_filter(command_tuple, False)
 
@@ -399,8 +421,8 @@ class SetFrameFilterPriority(gdb.Command):
 
     def _set_filter_priority(self,command_tuple):
         """Internal worker for setting priority of frame-filters, by
-        parsing a tuple and calling _set_filter_priority_1 with the
-        parsed tuple.
+        parsing a tuple and calling _set_priority with the parsed
+        tuple.
 
         Arguments:
             command_tuple: Tuple which contains the arguments from the
@@ -409,7 +431,7 @@ class SetFrameFilterPriority(gdb.Command):
 
         list_op = command_tuple[0]
         frame_filter = command_tuple[1]
-        priority = command_tuple [2]
+        priority = command_tuple[2]
 
         op_list = _return_list(list_op)
 
@@ -421,8 +443,9 @@ class SetFrameFilterPriority(gdb.Command):
 
         _set_priority(ff, priority)
 
-
     def complete (self,text,word):
+        """Completion function for both frame filter dictionary, and
+        frame filter name."""
         if text.count(" ") == 0:
             return _complete_frame_filter_list(text,word)
         else:
@@ -430,8 +453,6 @@ class SetFrameFilterPriority(gdb.Command):
             return _complete_frame_filter_name(word, printer_list)
 
     def invoke(self, arg, from_tty):
-        """GDB calls this to perform the command."""
-
         command_tuple = self._parse_pri_arg(arg)
         try:
             self._set_filter_priority(command_tuple)
@@ -505,6 +526,9 @@ class ShowFrameFilterPriority(gdb.Command):
         return _get_priority(ff)
 
     def complete (self,text,word):
+        """Completion function for both frame filter dictionary, and
+        frame filter name."""
+
         if text.count(" ") == 0:
             return _complete_frame_filter_list(text,word)
         else:
@@ -512,7 +536,6 @@ class ShowFrameFilterPriority(gdb.Command):
             return _complete_frame_filter_name(word, printer_list)
 
     def invoke(self, arg, from_tty):
-        """GDB calls this to perform the command."""
         try:
             command_tuple = self._parse_pri_arg(arg)
         except gdb.GdbError as e:
diff --git a/gdb/python/lib/gdb/frames.py b/gdb/python/lib/gdb/frames.py
index 1fdca5a..d23a0e6 100644
--- a/gdb/python/lib/gdb/frames.py
+++ b/gdb/python/lib/gdb/frames.py
@@ -50,16 +50,26 @@ def _sort_list():
     return sorted_frame_filters
 
 def execute_frame_filters(frame, frame_low, frame_high):
-    """ Public internal function that will execute the chain of frame
-    filters.  Each filter is executed in priority order.
+    """ Internal function that will execute the chain of frame
+    filters.  Each filter is executed in priority order.  After the
+    execution completes, slice the iterator to frame_low - frame_high
+    range.
 
     Arguments:
         frame: The initial frame.
 
+        frame_low: The low range of the slice.  If this is a negative
+        integer then it indicates a backward slice (ie bt -4) which
+        counts backward from the last frame in the backtrace.
+
+        frame_high:  The high range of the slice.  If this is a negative
+        integer then it indicates all frames until the end of the
+        stack from frame_low.
+
     Returns:
-        frame_iterator: The iterator after all frame filters have
-                        had a change to execute, or None if no frame
-                        filters are registered.
+        frame_iterator: The sliced iterator after all frame
+        filters have had a change to execute, or None if no frame
+        filters are registered.
     """
 
     # Get a sorted list of frame filters.
@@ -72,7 +82,7 @@ def execute_frame_filters(frame, frame_low, frame_high):
 
     frame_iterator = FrameIterator(frame)
 
-    # Apply base filter to all gdb.Frames.  This unifies the
+    # Apply a basic frame wrapper to all gdb.Frames.  This unifies the
     # interface.
     frame_iterator = itertools.imap(FrameWrapper, frame_iterator)
 
@@ -81,10 +91,12 @@ def execute_frame_filters(frame, frame_low, frame_high):
 
     # Slicing
 
-    # Is this a relative offset, ie bt -2?
+    # Is this a slice from the end of the backtrace, ie bt -2?
     if frame_low < 0:
         count = 0
         slice_length = abs(frame_low)
+        # We cannot use MAXLEN argument for deque as it is 2.6 onwards
+        # and some GDB versions might be < 2.6.
         sliced = collections.deque()
 
         for frame_item in frame_iterator:
@@ -95,13 +107,14 @@ def execute_frame_filters(frame, frame_low, frame_high):
 
         return iter(sliced)
 
-    # -1 for frame_high means until the end of the stack frame, and
-    # None means to the end of the iterator to islice.
+    # -1 for frame_high means until the end of the backtrace.  Set to
+    # None if that is the case, to indicate to itertools.islice to
+    # slice to the end of the iterator.
     if frame_high == -1:
         frame_high = None
     else:
         # The end argument for islice is a count, not a position, so
-        # add one as frames start as zero.
+        # add one as frames start at zero.
         frame_high = frame_high + 1;
 
     sliced = itertools.islice(frame_iterator, frame_low, frame_high)


hooks/post-receive
--
Repository for Project Archer.