Documentation structure confusing

[DigitalBrains1]

We use the following in clash-protocols.cabal:

  reexported-modules:
    Protocols.Plugin

The intent is to hide clash-protocols-base a bit more from the user. clash-protocols-base exposes that module, and clash-protocols merely reexports it. But this is not perfect.

1. The generated Haddock for clash-protocols does not actually include the Haddock for that module. It merely links to the Haddock for clash-protocols-base. So much for hiding.

   Also, it confused me. I opened the contents for clash-protocols, clicked the Protocols.Plugin module, then clicked the Contents header of that page and suddenly I was in the contents for clash-protocols-base even though I could have sworn I was looking at the documentation for clash-protocols. (To continue the saga, I drew the incorrect conclusion I must have had opened the wrong tab in my browser, started looking for the proper tab which didn't exist, and so on...). All in all, I find this a weird UX.

2. The Haddock for the Protocols module only documents the instances for Protocol that are defined in clash-protocols. The instances defined in clash-protocols-base are not listed. On the flip side, Protocols.Plugin only lists the instances for Protocols defined in clash-protocols-base (but that is pretty obvious as it doesn't know about clash-protocols).

3. Points 1 and 2 combine to: if you open the Haddock for clash-protocols and go to Protocols.Plugin, it will tell you that you can get more tuple instances for Protocols if you define the flag -flarge-tuples. But you need to define that flag for the clash-protocols-base package as well as for the clash-protocols package if you want other classes to get the same (but see issue clash-protocols should not use Protocols.Plugin.Cpp #119).