Fix idlelib.help comments (GH-15669)

Lib/idlelib/help.py

@@ -50,21 +50,22 @@ class HelpParser(HTMLParser):
     """
     def __init__(self, text):
         HTMLParser.__init__(self, convert_charrefs=True)
-        self.text = text         # text widget we're rendering into
-        self.tags = ''           # current block level text tags to apply
-        self.chartags = ''       # current character level text tags
-        self.show = False        # used so we exclude page navigation
-        self.hdrlink = False     # used so we don't show header links
-        self.level = 0           # indentation level
-        self.pre = False         # displaying preformatted text
-        self.hprefix = ''        # prefix such as '25.5' to strip from headings
-        self.nested_dl = False   # if we're in a nested <dl>
-        self.simplelist = False  # simple list (no double spacing)
-        self.toc = []            # pair headers with text indexes for toc
-        self.header = ''         # text within header tags for toc
-        self.prevtag = None      # info about previous tag (was opener, tag)
+        self.text = text         # Text widget we're rendering into.
+        self.tags = ''           # Current block level text tags to apply.
+        self.chartags = ''       # Current character level text tags.
+        self.show = False        # Exclude html page navigation.
+        self.hdrlink = False     # Exclude html header links.
+        self.level = 0           # Track indentation level.
+        self.pre = False         # Displaying preformatted text?
+        self.hprefix = ''        # Heading prefix (like '25.5'?) to remove.
+        self.nested_dl = False   # In a nested <dl>?
+        self.simplelist = False  # In a simple list (no double spacing)?
+        self.toc = []            # Pair headers with text indexes for toc.
+        self.header = ''         # Text within header tags for toc.
+        self.prevtag = None      # Previous tag info (opener?, tag).
 
     def indent(self, amt=1):
+        "Change indent (+1, 0, -1) and tags."
         self.level += amt
         self.tags = '' if self.level == 0 else 'l'+str(self.level)
 
@@ -76,12 +77,12 @@ class HelpParser(HTMLParser):
                 class_ = v
         s = ''
         if tag == 'div' and class_ == 'section':
-            self.show = True    # start of main content
+            self.show = True    # Start main content.
         elif tag == 'div' and class_ == 'sphinxsidebar':
-            self.show = False   # end of main content
+            self.show = False   # End main content.
         elif tag == 'p' and self.prevtag and not self.prevtag[0]:
-            # begin a new block for <p> tags after a closed tag
-            # avoid extra lines, e.g. after <pre> tags
+            # Begin a new block for <p> tags after a closed tag.
+            # Avoid extra lines, e.g. after <pre> tags.
             lastline = self.text.get('end-1c linestart', 'end-1c')
             s = '\n\n' if lastline and not lastline.isspace() else '\n'
         elif tag == 'span' and class_ == 'pre':
@@ -103,7 +104,7 @@ class HelpParser(HTMLParser):
         elif tag == 'li':
             s = '\n* ' if self.simplelist else '\n\n* '
         elif tag == 'dt':
-            s = '\n\n' if not self.nested_dl else '\n'  # avoid extra line
+            s = '\n\n' if not self.nested_dl else '\n'  # Avoid extra line.
             self.nested_dl = False
         elif tag == 'dd':
             self.indent()
@@ -129,12 +130,13 @@ class HelpParser(HTMLParser):
     def handle_endtag(self, tag):
         "Handle endtags in help.html."
         if tag in ['h1', 'h2', 'h3']:
-            self.indent(0)  # clear tag, reset indent
+            assert self.level == 0
             if self.show:
                 indent = ('        ' if tag == 'h3' else
                           '    ' if tag == 'h2' else
                           '')
                 self.toc.append((indent+self.header, self.text.index('insert')))
+            self.tags = ''
         elif tag in ['span', 'em']:
             self.chartags = ''
         elif tag == 'a':
@@ -143,7 +145,7 @@ class HelpParser(HTMLParser):
             self.pre = False
             self.tags = ''
         elif tag in ['ul', 'dd', 'ol']:
-            self.indent(amt=-1)
+            self.indent(-1)
         self.prevtag = (False, tag)
 
     def handle_data(self, data):
@@ -169,7 +171,7 @@ class HelpText(Text):
         "Configure tags and feed file to parser."
         uwide = idleConf.GetOption('main', 'EditorWindow', 'width', type='int')
         uhigh = idleConf.GetOption('main', 'EditorWindow', 'height', type='int')
-        uhigh = 3 * uhigh // 4  # lines average 4/3 of editor line height
+        uhigh = 3 * uhigh // 4  # Lines average 4/3 of editor line height.
         Text.__init__(self, parent, wrap='word', highlightthickness=0,
                       padx=5, borderwidth=0, width=uwide, height=uhigh)
 
@@ -209,7 +211,6 @@ class HelpFrame(Frame):
     "Display html text, scrollbar, and toc."
     def __init__(self, parent, filename):
         Frame.__init__(self, parent)
-        # keep references to widgets for test access.
         self.text = text = HelpText(self, filename)
         self['background'] = text['background']
         self.toc = toc = self.toc_menu(text)
@@ -217,7 +218,7 @@ class HelpFrame(Frame):
         text['yscrollcommand'] = scroll.set
 
         self.rowconfigure(0, weight=1)
-        self.columnconfigure(1, weight=1)  # text
+        self.columnconfigure(1, weight=1)  # Only expand the text widget.
         toc.grid(row=0, column=0, sticky='nw')
         text.grid(row=0, column=1, sticky='nsew')
         scroll.grid(row=0, column=2, sticky='ns')
@@ -279,7 +280,7 @@ def show_idlehelp(parent):
     "Create HelpWindow; called from Idle Help event handler."
     filename = join(abspath(dirname(__file__)), 'help.html')
     if not isfile(filename):
-        # try copy_strip, present message
+        # Try copy_strip, present message.
         return
     HelpWindow(parent, filename, 'IDLE Help (%s)' % python_version())