address remarks

Author: carbolymer

docs/ADR-X-cardano-api-exports-convention.md

@@ -4,6 +4,8 @@
 
 # Context
 
+TODO
+
 # Proposed Design
 
 ## Top level exports
@@ -12,32 +14,81 @@ Each top level export should export distinct symbols.
 This may depend on the case, for example: `Cardano.Api.Byron` symbols which are still in use in current eras, can be reexported through `Cardano.Api`.
 
 * `Cardano.Api` - everything domain related for the currently used and upcoming eras
-* `Cardano.Api.E` - everything for the obsoleted `E` era, for example `Cardano.Api.Byron`.
-  1. Any symbol from era `E`, not in use in current era, should be exported through `Cardano.Api.E`.
-  2. Any symbol from era `E` and still in use in current era, should be exported through `Cardano.Api` and additionally through `Cardano.Api.E`.
-    If that's not possible to move it to a module under `Cardano.Api` module, the symbol should be copied to a module under `Cardano.Api`.
-* `Cardano.Api.U` utility module, related to `U` feature set like, like `Cardano.Api.Pretty`, `Cardano.Api.Monad.Error`.
-  Those should **not** be reexported from `Cardano.Api`, because they would pollute symbol namespace, and are not required for using `cardano-api` core features but can be useful for the advanced users.
-  1. Reexports from upstream libraries like consensus, network or ledger, also fall into this category e.g. `Cardano.Api.Ledger`.
 
-  Modules which are exposing general purpose classes and functions should go also into a separate module, and they not need to be reexported through `Cardano.Api`, for example:
-  * `Cardano.Api.Tx.UTxO` - a wrapper type, with functions common to maps which would clash with other map data structures.
-    A good example from Hackage is [`Data.Aeson.KeyMap`](https://hackage.haskell.org/package/aeson-2.2.3.0/docs/Data-Aeson-KeyMap.html).
+* `Cardano.Api.<F>`, where `<F>` represents a feature.
+  An aggregate module providing one of core `cardano-api` functionalities.
+  The name has to be a singular noun.
+  The purpose of this export is to provide users a more granular control of imports if they don't want to import a catch-all `Cardano.Api` module.
+  For example:
+
+    * `Cardano.Api.Address`
+    * `Cardano.Api.Block`
+    * `Cardano.Api.Certificate`
+    * `Cardano.Api.Eon`
+    * `Cardano.Api.Genesis`
+    * `Cardano.Api.Governance`
+    * `Cardano.Api.IPC`
+    * `Cardano.Api.Key`
+    * `Cardano.Api.LedgerState`
+    * `Cardano.Api.Query`
+    * `Cardano.Api.Serialisation`
+    * `Cardano.Api.Tx`
+
+  The following rules apply:
+
+  1. The modules should not be very granular, only related to a particular feature set.
+     For example
+
+     * `Cardano.Api.Governance.Actions.ProposalProcedure` should not be a top level export and should be exported through `Cardano.Api.Governance`.
+     * `Cardano.Api.LedgerEvents` should not be a top level export and should be exported through `Cardano.Api.LedgerState`.
+
+  1. The module should be reexported through `Cardano.Api`.
+    This makes using `cardano-api` easier, by not forcing users to decide what to import, and allowing them to just simply write `import Cardano.Api`.
+
+* `Cardano.Api.Byron` - everything for the obsoleted Byron era
+
+* `Cardano.Api.Compatible` - everything for the older eras.
+  The purpose of this module to provide a limited backwards compatibility for eras not in use on Cardano mainnet.
+  This is meant only for supporting of tests which hardfork through eras.
 
+  For both `Cardano.Api.Byron` and `Cardano.Api.Compatible` the following rules apply:
+
+  1. Any symbol from previous era, not in use in current era, should be exported through the respective module for older eras.
+  2. Any symbol from previous era and still in use in the current era, should be exported through `Cardano.Api` and additionally through `Cardano.Api.(Byron|Compatible)`.
+
+* `Cardano.Api.Experimental` - a transient module for implementing new not yet stabilised APIs.
+  Not meant to be used by `cardan-api` users directly.
+
+* `Cardano.Api.<U>` utility module, where `<U>` represents a utilities set.
+  For example `Cardano.Api.Pretty`, `Cardano.Api.Monad.Error`.
+
+  * Reexports from upstream libraries like consensus, network or ledger, also fall into this category e.g. `Cardano.Api.Ledger`.
+
+  * Modules which are exposing general purpose classes and functions should go also into a separate module, and they don't need to be reexported through `Cardano.Api`.
+    For example `Cardano.Api.Tx.UTxO` - a wrapper type, with functions common to maps which would clash with other map data structures.
+    A good example of this pattern from Hackage is [`Data.Aeson.KeyMap`](https://hackage.haskell.org/package/aeson-2.2.3.0/docs/Data-Aeson-KeyMap.html).
+
+  In principle, those should not be reexported from `Cardano.Api`, because they would pollute symbol namespace, and are not required for using `cardano-api` core features but can be useful for the advanced users.
+    In certain situations, parts of those modules can be reexported from `Cardano.Api`, to provide more seamless experience of using the main `Cardano.Api` module.
 
 ## Deeper level exports
 
-Any other modules not meant to be a top level export, should be placed inside `Cardano.Api.Internal` and be reexported through a suitable top level module.
-In general `Cardano.Api.Internal.*` modules shouldn't be exposed in cabal package.
+Any other modules not meant to be a top level export, should be placed inside `Cardano.Api.Internal` or `Cardano.Api.<X>.Internal` and be reexported through a suitable top level module.
+In general internal modules shouldn't be exposed in cabal package, but it may be necessary for using them from other components in `cardano-api`, like tests.
 This however depends on the specific use case.
 `Internal` in the module name should indicate that the module isn't really meant to be used directly, and users can expect more frequent breakage when relying on it.
 
-* `Cardano.Api.Internal.X` should contain everything related to the domain `X`.
-  For example `Cardano.Api.Address`.
-  A good example from Hackage how to nest `Internal` modules is [`bytestring`](https://github.com/haskell/text/blob/master/src/Data/Text/Internal/Builder/RealFloat/Functions.hs) package.
+* `Cardano.Api.<X>.Internal` or `Cardano.Api.Internal.<X>` or should contain everything related to the domain `<X>`.
+  * If `Cardano.Api.<X>` is a top level export, internal functions should go to `Cardano.Api.<X>.Internal` (e.g. `Cardano.Api.Address.Internal`), otherwise
+  * if there's no `Cardano.Api.<X>` top level export, internal functions should go to `Cardano.Api.Internal.<X>` (e.g. `Cardano.Api.Internal.Orphans`).
+  
+  A good example from Hackage how to nest `Internal` modules is [`text`](https://github.com/haskell/text/blob/master/src/Data/Text/Internal/Builder/RealFloat/Functions.hs) package.
 
 # Decision
 
+TODO
 
 # Consequences
 
+TODO
+