Document tidyProgram

The important function tidyProgram is sadly un-documented. See this ghc-devs conversation.

It should have a Note like Note [CorePrep Overview] in GHC.CoreToStg.Prep.

I think the invariants of tidyProgram are these. In the the output of tidyProgram:

• There is no shadowing of OccNames. In Core it is fine to have (\x_22. \x_31. x_22), but tidying will convert it to \x. \x1. x, where the OccNames no longer shadow. Main reason: when we serialise to the interface file, we use the OccName alone, not the unique.

• "Implicit bindings" have been added, such as data constructor wrappers and class method selectors. See Note [Injecting implicit bindings]). These bindings are not subject to the Simplifier (which can't improve them), but we need to generate code for them.

• ...probably some more...

• A non-invariant: tidyProgram does not ensure that all Uniques are globally unique. That is done by CorePrep.

One point I note is that the implicit_binds in GHC.Iface.Tidy.tidyProgram are not themselves tidied, so there is no a priori reason to suppose that they satisfy the "no-shadowing-of-OccNames" condition. At very least we should document the invariant that all implicit bindings are pre-tidied. See #21363