PLT-7891 Add a few docstrings to the indexers

marconi-cardano-indexers/src/Marconi/Cardano/Indexers/BlockInfo.hs

@@ -6,7 +6,7 @@
 {-# LANGUAGE TemplateHaskell #-}
 {-# LANGUAGE ViewPatterns #-}
 
--- | An Indexer that stores BlockInfo
+-- | An Indexer that stores BlockInfo (timestamp, block header hash, epoch number and block number of each block)
 module Marconi.Cardano.Indexers.BlockInfo (
   -- * Event
   BlockInfo (BlockInfo),
@@ -87,7 +87,7 @@ type BlockInfoIndexer = Core.SQLiteIndexer BlockInfo
 type StandardBlockInfoIndexer m = StandardSQLiteIndexer m BlockInfo
 
 instance SQL.ToRow (Core.Timed C.ChainPoint BlockInfo) where
-  toRow b = SQL.toRow (b ^. Core.point) ++ SQL.toRow (b ^. Core.event)
+  toRow b = SQL.toRow (b ^. Core.point) <> SQL.toRow (b ^. Core.event)
 
 instance SQL.ToRow BlockInfo where
   toRow b =

marconi-cardano-indexers/src/Marconi/Cardano/Indexers/Datum.hs

@@ -7,6 +7,14 @@
 {-# LANGUAGE TemplateHaskell #-}
 {-# LANGUAGE ViewPatterns #-}
 
+{- | The datum indexer stores datum (as 'Cardano.Api.ScriptData')
+ with their hash, and information about the first slot where these
+ data appear on chain.
+
+ Note that we don't store all the occurences of the data onchain.
+ So if you want to check if a datum is present in a given transaction,
+ you need to join this indexer with an indexer that contains this information.
+-}
 module Marconi.Cardano.Indexers.Datum (
   -- * Event
   DatumInfo (DatumInfo),
@@ -105,8 +113,10 @@ mkDatumIndexer
 mkDatumIndexer path = do
   let createDatumQuery =
         [sql|CREATE TABLE IF NOT EXISTS datum
+             -- we store datum once disregarding how often it appears onchain
              ( datumHash BLOB PRIMARY KEY
              , datum BLOB
+             -- ChainPoint: the first occurence of a datum
              , slotNo INT
              , blockHeaderHash BLOB
              )|]

marconi-cardano-indexers/src/Marconi/Cardano/Indexers/EpochSDD.hs

@@ -5,7 +5,7 @@
 {-# LANGUAGE QuasiQuotes #-}
 {-# LANGUAGE TemplateHaskell #-}
 
--- | Store SDD in a SQLIte table
+-- | Store the Stakepool delegation distribution in a SQLIte table
 module Marconi.Cardano.Indexers.EpochSDD (
   -- * Event types and lenses
   EpochSDD (EpochSDD),

marconi-cardano-indexers/src/Marconi/Cardano/Indexers/Spent.hs

@@ -7,6 +7,10 @@
 {-# LANGUAGE ViewPatterns #-}
 {-# OPTIONS_GHC -Wno-orphans #-}
 
+{- | This indexer tracks the spent transaction outputs:
+ the outputs that are spent as tx input in a transaction.
+ We track the transaction where they are spent and its block.
+-}
 module Marconi.Cardano.Indexers.Spent (
   -- * Event
   SpentInfo (SpentInfo),

marconi-cardano-indexers/src/Marconi/Cardano/Indexers/Utxo.hs

@@ -19,6 +19,19 @@
 {-# LANGUAGE ViewPatterns #-}
 {-# OPTIONS_GHC -Wno-orphans #-}
 
+{- |
+ Host an indexer that stores all the transaction outputs and
+ many of their relative information
+
+ * transaction that created them
+ * hash of their datum datum
+ * script info
+
+ It also includes helper function to extract the corresponding
+ data from a block or from a TxBody.
+
+ Note that we don't remove spent tx outputs from this indexer.
+-}
 module Marconi.Cardano.Indexers.Utxo (
   -- * Event
   Utxo (Utxo),
@@ -117,7 +130,9 @@ Lens.makeLenses ''Utxo
 
 data UtxoIndexerConfig = UtxoIndexerConfig
   { _trackedAddresses :: [C.AddressAny]
+  -- ^ Allow us to filter the UTxOs we want to index
   , _includeScript :: Bool
+  -- ^ Do we store script info
   }
 
 Lens.makeLenses ''UtxoIndexerConfig
@@ -226,7 +241,7 @@ utxoWorker workerConfig utxoConfig path = do
       indexer
 
 {- | Convenience wrapper around 'utxoWorker' with some defaults for
-creating 'StandardWorkerConfig', including a preprocessor.
+creating 'StandardWorkerConfig', including a preprocessor for resuming and an address filter.
 -}
 utxoBuilder
   :: (MonadIO n, MonadError Core.IndexerError n)

marconi-core/src/Marconi/Core/Transformer/WithCatchup.hs

@@ -9,7 +9,12 @@
  the blocks to the indexer.
 
  When you use several workers and coordinators, you may want to put the catchup on the final
- indexers and not on the coordinators to improve performances.
+ indexers and not on the coordinators to improve performances
+
+ Similarly, if you want to filter the events before sending them to the indexer
+ (for example, using 'WithTransform'), you should do it after the catchup, to  ensure that
+ each event is properly handle by the catchup.
+ If you don't do it, batch can be send very late to the indexer and it would impact resuming.
 -}
 module Marconi.Core.Transformer.WithCatchup (
   WithCatchup,