Document `resolve` behaviour better

[chshersh]

It's not obvious from current documentation for resolve and some universe sense how this function handles module reexports.

Consider next two Haskell modules:

module Example.Internal (details) where

details :: Int -> String
details = undefined

module Example (details) where

import           Example.Internal

There're several possibilities how exported by Example module symbols can be resolved. But not all possibilities work properly. And it's not obvious which one works and how. I've tried to experiment with them and see differences. You can observe my experiments and results here.

[phischu]

Thank you for your report. To me these results look correct and expected, but that's because I know the library :). What did surprise you?

Your code looks great perhaps we can add it as an example how to use the library and what to expect?

[chshersh]

@phischu You can add my code to library documentation. It would be great!

I wasn't so surprised... Just spend some time on experimenting with library to find out whether it's possible to do desired things and if yes then how.

1. It wasn't clear that resolve can handle reexports from other modules (I was realy glad that haskell-names can handle such situations but first I tried to resolve each module independently to make things faster instead processing all of them in single list).
2. It's not clear that resolve handles list of Modules at once, not one by one (first, then second using information from first, then third using information from first and second). So order doesn't matter and I don't need to sort modules topologically before putting them in list.
3. Moreover, if Internal is already in Environment then [Module l] will have access to exported symbols by current env. List (first argument) is not processed independently from env (second argument).
4. But! According to last example in my repo — values in given Environment are not updated with elements from list.

Basically, all elements in lists can use information about each others. And they can use information from Environment but Environment doesn't use information from list of modules to update already present values. If I wrote this in some notation I would do it like this:

Module ↔ Module Module → Environment

where arrow A → B means that A can use information from B to configure Environment properly.