Reflow paragraphs in comments.

[aprantl]

Summary

This is intended as a clean up after the big clang-format commit (r280751), which unfortunately resulted in many of the comment paragraphs in LLDB being very hard to read.

FYI the script I used was:

import textwrap
import commands
import os
import sys
import re
tmp = "%s.tmp"%sys.argv[1]
out = open(tmp, "w+")
with open(sys.argv[1], "r") as f:
  header = ""
  text = ""
  for line in f:
      comment = re.compile(r'^( *//) ([^ ].*)$')
      match = comment.match(line)
      if match:
          # skip intentionally short comments.
          if not text and len(match.group(2)) < 40:
              out.write(line)
              continue

          if text:
              text += " " + match.group(2)
          else:
              header = match.group(1)
              text = match.group(2)
          
          continue
      else:
          if text:
              filled = textwrap.wrap(text, width=(73-len(header)),
                                     break_long_words=False)
              for l in filled:
                  out.write(header+" "+l+'\n')
              text = ""

      out.write(line)

os.rename(tmp, sys.argv[1])
#find source -name '*.cpp' -exec python join-comments.py \{} \;

[labath]

The formatting of the comments has been bugging me as well. So far, I have been trying to reflow them whenever I touch the code around them, but at that rate fixing all of them would take ages.

Your heuristics seem to be working fairly well. I've found a couple of sub-optimal decisions in the few files I opened, but I am not sure if it's feasible to fix the algorithm to account for them.

So overall, this seems like a good idea to me, and the few places where it gets this wrong can be fixed up afterwards (it decreases the total number of badly formatted comments).

PS: I don't see any header files in the list. Is there a particular reason for skipping them?

source/API/SBDebugger.cpp

73 ↗

(On Diff #144194)

Folding TODO: Here is sub-optimal.

source/API/SBInstruction.cpp

37–38 ↗

(On Diff #144194)

This doesn't look right.

[aprantl]

Updated the script based on Pavel's feedback:

import textwrap
import commands
import os
import sys
import re
tmp = "%s.tmp"%sys.argv[1]
out = open(tmp, "w+")
with open(sys.argv[1], "r") as f:
  header = ""
  text = ""
  comment = re.compile(r'^( *//) ([^ ].*)$')
  special = re.compile(r'^(([A-Z]+[: ])|([0-9]+ )).*$')
  for line in f:
      match = comment.match(line)
      if match and not special.match(match.group(2)):
          # skip intentionally short comments.
          if not text and len(match.group(2)) < 40:
              out.write(line)
              continue

          if text:
              text += " " + match.group(2)
          else:
              header = match.group(1)
              text = match.group(2)
          
          continue

      if text:
          filled = textwrap.wrap(text, width=(77-len(header)),
                                 break_long_words=False)
          for l in filled:
              out.write(header+" "+l+'\n')
              text = ""

      out.write(line)

os.rename(tmp, sys.argv[1])
#find source -name '*.cpp' -exec python join-comments.py \{} \;

[labath]

Looks fine to me, I guess if noone objects, we can land this. Thanks for doing this.

[JDevlieghere]

👍

source/Host/common/MainLoop.cpp

158 ↗

(On Diff #144420)

Is this intentional or maybe an off-by-one error? The a is in the 79th colum, which is okay for clang-format.

[aprantl]

source/Host/common/MainLoop.cpp

158 ↗

(On Diff #144420)

My script sets the threshold to 78 columns. When you are on an 80-column terminal and your editor doesn't indicate whether long lines continue or not then not using the last two characters makes it unambiguous whether the a is the beginning of a new word or whether it stands for itself.
I'll change the threshold to 80 columns to avoid reflowing paragraphs that don't need it.