Automate the maintenance of base-compat's export lists

[RyanGlScott]

In #48, @phadej brought up that we should be using explicit export lists more often than we currently do, since:

1. It leads to nicer-looking Haddocks.
2. It provides a slightly stronger guarantee that we're providing the same API on different versions of base. (This isn't a foolproof guarantee, since it's possible the types of functions could be different across different versions of base. But for those cases, we should be able to test for that.)
3. Using explicit re-exports is a bit dodgy from a PVP perspective.

That being said, keeping explicit export lists up-to-date with the latest version of base is a huge timesink. It would be far preferable if there were a way to automatically scrape this information from base itself.

I imagine there will be some complications involved, since base-compat often uses CPP in its export lists at the moment. But perhaps we can defer all of the CPP to the rest of the module instead, and leave the export list unaltered, it that would make things easier to automate.

[RyanGlScott]

Question: what should we put in the module-level Haddocks? Should we put:

1. The original Haddocks from base?
2. A list things we backport?
3. Some combination of the two?

[sol]

At least my original idea was not to worry about the Haddocks too much and refer users to the documentation of the latest version of base.

When built with the latest version of GHC (what Hackage does, and what is hence used for the Haddocks on Hackage at least), then {X}.Compat and {X} should be equivalent anyway, right?

[RyanGlScott]

When built with the latest version of GHC (what Hackage does, and what is hence used for the Haddocks on Hackage at least), then {X}.Compat and {X} should be equivalent anyway, right?

Unfortunately, no. At least, not as far as the presentation of Haddocks is concerned. Compare the Haddocks for Data.Bool and Data.Bool.Compat, for instance. The latter only contains one explicit Haddock snippet (for the bool function) and simply defers to "module Data.Bool" for the rest, which means that users have to go through an extra indirection to see the remaining Haddocks.

[sol]

What I actually meant is:

1. The docs for both Data.Bool and Data.Bool.Compat are build with the latest version of GHC
2. The API of Data.Bool and Data.Bool.Compat are exactly the same provide we use the latest version of GHC
3. If we now put effort into the docs of Data.Bool.Compat the best we can achieve is parity with Data.Bool, so a user could just look at Data.Bool directly instead.

This is as far as Hackage is concerned and assuming that we are only interested in the latest version of base-compat.

When you build the Haddocks locally with an older version of GHC on the other hand then you can get a slightly different API than what is in base and hence the documentation could be slightly different from the corresponding modules in base. So here it could be beneficial to do something about documentation.

My point was, if we only care about Hackage then I think better documentation for base-compat would not add much.

Does this make sense?

[RyanGlScott]

Ultimately, it's @phadej who cares the most about this issue, not me. I think I'll let him answer this question.

[phadej]

I'm not concerned about haddocks, I'm concerned about explicit export lists, vs. re-exporting the module.

If we extend tests to include all modules (i noticed there are only a handful), then the tests will catch if there are differences. I suspect that there might be issues. I'm afraid that without explicit export lists and tests we may forget to shim some new things/changes happening in base.

Also we have modules like

• http://hackage.haskell.org/package/base-compat-0.10.5/docs/src/Data.Either.Compat.html re-export
• http://hackage.haskell.org/package/base-compat-0.10.5/docs/src/Data.Semigroup.Compat.html explicit list

This non-uniformity is non-clear to me.