docs: def extract_comments(
      lines: List[Tuple[int, str]]
  ) -> Tuple[List[Tuple[int, str]], Dict[str, List[str]]]:
      """Given a list of numbered lines from a Fortran file where comments
         internal to subprogram bodies have been moved out into their own lines,
         extract_comments() extracts comments into a dictionary and replaces
         each comment internal to subprogram bodies with a marker statement.
         It returns a pair (code, comments) where code is a list of numbered
         lines with comments removed and marker statements (plus corresponding
         variable declarations) added; and comments is a dictionary mapping
         marker statement variables to the corresponding comments."""
  
      curr_comment = []
      curr_fn, prev_fn, curr_marker = None, None, None
      comments = OrderedDict()
  
      # curr_state refers to the state of the finite-state machine (see above)
      curr_state = "outside"
  
      comments["$file_head"] = []
      comments["$file_foot"] = []
  
      for i in range(len(lines)):
          (linenum, line) = lines[i]
  
          # determine what kind of line this is
          line_type = type_of_line(line)
  
          # process the line appropriately
          if curr_state == "outside":
              assert line_type in ("comment", "pgm_unit_start"), (
                  line_type,
                  line,
              )
              if line_type == "comment":
                  curr_comment.append(line)
                  lines[i] = (linenum, None)
              else:
                  # line_type == "pgm_unit_start"
                  pgm_unit_name = program_unit_name(line)
                  comments["$file_head"] = curr_comment
  
                  if prev_fn is not None:
                      comments[prev_fn]["foot"] = curr_comment
  
                  prev_fn = curr_fn
                  curr_fn = pgm_unit_name
  
                  internal_comments = OrderedDict()
  
                  comments[curr_fn] = init_comment_map(
                      curr_comment, [], [], internal_comments
                  )
                  curr_comment = []
  
          elif curr_state == "in_neck":
              assert line_type in ("comment", "exec_stmt", "other")
              if line_type == "comment":
                  curr_comment.append(line)
                  lines[i] = (linenum, None)
              elif line_type == "exec_stmt":
                  comments[curr_fn]["neck"] = curr_comment
                  curr_comment = []
              else:
                  pass  # nothing to do -- continue
  
          elif curr_state == "in_body":
              assert line_type in (
                  "comment",
                  "exec_stmt",
                  "pgm_unit_end",
              ), f"[Line {linenum}]: {line}"
  
              if line_type == "comment":
                  # Ignore empty lines, which are technically comments but which
                  # don't contribute any semantic content.
                  if line != "\n":
                      marker_var = f"{INTERNAL_COMMENT_PREFIX}_{linenum}"
                      marker_stmt = f"        {marker_var} = .True.\n"
                      internal_comments[marker_var] = line
                      lines[i] = (linenum, marker_stmt)
              else:
                  pass  # nothing to do -- continue
  
          # update the current state
          curr_state = TRANSITIONS[curr_state][line_type]
  
      # if there's a comment at the very end of the file, make it the foot
      # comment of curr_fn
      if curr_comment != [] and comments.get(curr_fn):
          comments[curr_fn]["foot"] = curr_comment
          comments["$file_foot"] = curr_comment
  
      return (lines, comments)