[core] Documentation and cleanups for LifetimeTracker

[jimblandy]

• Use a for loop in LifetimeTracker triage code.

  A for loop is less noisy here than a drain, which requires:

  • a mut qualifier for a variable whose modified value we never
    consult

  • a method name appearing mid-line instead of a control structure name
    at the front of the line

  • a range which is always .., establishing no restriction at all

  • a closure instead of a block

  Structured control flow syntax has a fine pedigree, originating in,
  among other places, Dijkstrsa's efforts at designing languages in a
  way that made it easier to formally verify programs written in
  them (see "A Discipline Of Programming"). There is nothing "more
  mathematical" about a method call that takes a closure than a for
  loop. Since for_each is useless unless the closure has side effects,
  there's nothing "more functional" about for_each here, either.
  Obsessive use of for_each suggests that the author loves Haskell
  without understanding it.

• In LifetimeTrackers triage code, use more specific names.

  Rename LifetimeTracker::triage_resources's resources_map argument
  to suspected_resources, since this always points to a field of
  LifetimeTracker::suspected_resources.

  In the various triage_suspected_foo functions, name the map
  suspected_foos.

• Refactor LifetimeTracker::triage_resources.

  Check whether the resource is abandoned first, since none of the rest
  of the work is necessary otherwise.

  Rename non_referenced_resources to last_resources. This function
  copes with various senses in which the resource might be referenced or
  not. Instead, last_resources is the name of the ActiveSubmission
  member this may point to, which is more specific.

  Move the use of last_resources immediately after its production.

• Doc fixes for lifetime management, minor typos.

  • Document LifetimeTracker::triage_resources.

  • Fix various typos and bad grammar.

[jimblandy]

Since I indulged in a rant: There is at least one case where for_each makes sense: at the end of a long chain of iterator adaptors. In that case, a for_each loop puts the variables being bound for each iteration right above the code that uses them, rather than at the head of the for loop, on the far side of the iterator chain.

[cwfitzgerald]

... for loops ...

I agree, never been a big fan of for_each.