doc: document TableConfig

Author: wenkokke

README.md

@@ -119,11 +119,11 @@ constants:
 - The variable *b* usually refers to the size of a batch of
   inputs/outputs. Its precise meaning is explained for each occurrence.
 
-- The constant *B* refers to the size of the write buffer, which is a
-  configuration parameter.
+- The constant *B* refers to the size of the write buffer, which is
+  determined by the `TableConfig` parameter `confWriteBufferAlloc`.
 
-- The constant *T* refers to the size ratio of the table, which is a
-  configuration parameter.
+- The constant *T* refers to the size ratio of the table, which is
+  determined by the `TableConfig` parameter `confSizeRatio`.
 
 - The constant *P* refers to the the average number of key–value pairs
   that fit in a page of memory.
@@ -133,7 +133,8 @@ constants:
 The following table summarises the cost of the operations on LSM-trees
 measured in the number of disk I/O operations. If the cost depends on
 the merge policy, the table contains one entry for each merge policy.
-Otherwise, the merge policy is listed as N/A.
+Otherwise, the merge policy is listed as N/A. The merge policy is
+determined by the `TableConfig` parameter `confMergePolicy`.
 
 <table>
 <thead>
@@ -266,9 +267,9 @@ The worst-case in-memory size of an LSM-tree is *O*(*n*).
 - The worst-case in-memory size of the write buffer is *O*(*B*).
 
   The maximum size of the write buffer on the write buffer allocation
-  strategy, which is determined by the `confWriteBufferAlloc` field of
-  `TableConfig`. Regardless of write buffer allocation strategy, the
-  size of the write buffer may never exceed 4GiB.
+  strategy, which is determined by the `TableConfig` parameter
+  `confWriteBufferAlloc`. Regardless of write buffer allocation
+  strategy, the size of the write buffer may never exceed 4GiB.
 
   `AllocNumEntries maxEntries`  
   The maximum size of the write buffer is the maximum number of entries
@@ -279,8 +280,8 @@ The worst-case in-memory size of an LSM-tree is *O*(*n*).
   The total in-memory size of all Bloom filters is the number of bits
   per physical entry multiplied by the number of physical entries. The
   required number of bits per physical entry is determined by the Bloom
-  filter allocation strategy, which is determined by the
-  `confBloomFilterAlloc` field of `TableConfig`.
+  filter allocation strategy, which is determined by the `TableConfig`
+  parameter `confBloomFilterAlloc`.
 
   `AllocFixed bitsPerPhysicalEntry`  
   The number of bits per physical entry is specified as
@@ -304,9 +305,9 @@ The worst-case in-memory size of an LSM-tree is *O*(*n*).
 - The worst-case in-memory size of the indexes is *O*(*n*).
 
   The total in-memory size of all indexes depends on the index type,
-  which is determined by the `confFencePointerIndex` field of
-  `TableConfig`. The in-memory size of the various indexes is described
-  in reference to the size of the database in [*memory
+  which is determined by the `TableConfig` parameter
+  `confFencePointerIndex`. The in-memory size of the various indexes is
+  described in reference to the size of the database in [*memory
   pages*](https://en.wikipedia.org/wiki/Page_%28computer_memory%29 "https://en.wikipedia.org/wiki/Page_%28computer_memory%29").
 
   `OrdinaryIndex`  

lsm-tree.cabal

@@ -71,8 +71,10 @@ description:
   *   The variable \(s\) refers to the number of snapshots in the session.
   *   The variable \(b\) usually refers to the size of a batch of inputs\/outputs.
       Its precise meaning is explained for each occurrence.
-  *   The constant \(B\) refers to the size of the write buffer, which is a configuration parameter.
-  *   The constant \(T\) refers to the size ratio of the table, which is a configuration parameter.
+  *   The constant \(B\) refers to the size of the write buffer,
+      which is determined by the @TableConfig@ parameter @confWriteBufferAlloc@.
+  *   The constant \(T\) refers to the size ratio of the table,
+      which is determined by the @TableConfig@ parameter @confSizeRatio@.
   *   The constant \(P\) refers to the the average number of key–value pairs that fit in a page of memory.
 
   === Disk I\/O cost of operations #performance_time#
@@ -81,6 +83,7 @@ description:
   measured in the number of disk I\/O operations.
   If the cost depends on the merge policy, the table contains one entry for each merge policy.
   Otherwise, the merge policy is listed as N\/A.
+  The merge policy is determined by the @TableConfig@ parameter @confMergePolicy@.
 
   +----------+------------------------+----------------------------+------------------------------------------------+
   | Resource | Operation              | Merge policy               | Cost in disk I\/O operations                   |
@@ -131,7 +134,8 @@ description:
 
   *   The worst-case in-memory size of the write buffer is \(O(B)\).
 
-      The maximum size of the write buffer on the write buffer allocation strategy, which is determined by the @confWriteBufferAlloc@ field of @TableConfig@.
+      The maximum size of the write buffer on the write buffer allocation strategy,
+      which is determined by the @TableConfig@ parameter @confWriteBufferAlloc@.
       Regardless of write buffer allocation strategy, the size of the write buffer may never exceed 4GiB.
 
       [@AllocNumEntries maxEntries@]:
@@ -140,7 +144,8 @@ description:
   *   The worst-case in-memory size of the Bloom filters is \(O(n)\).
 
       The total in-memory size of all Bloom filters is the number of bits per physical entry multiplied by the number of physical entries.
-      The required number of bits per physical entry is determined by the Bloom filter allocation strategy, which is determined by the @confBloomFilterAlloc@ field of @TableConfig@.
+      The required number of bits per physical entry is determined by the Bloom filter allocation strategy,
+      which is determined by the @TableConfig@ parameter @confBloomFilterAlloc@.
 
       [@AllocFixed bitsPerPhysicalEntry@]:
           The number of bits per physical entry is specified as @bitsPerPhysicalEntry@.
@@ -165,7 +170,8 @@ description:
 
   *   The worst-case in-memory size of the indexes is \(O(n)\).
 
-      The total in-memory size of all indexes depends on the index type, which is determined by the @confFencePointerIndex@ field of @TableConfig@.
+      The total in-memory size of all indexes depends on the index type,
+      which is determined by the @TableConfig@ parameter @confFencePointerIndex@.
       The in-memory size of the various indexes is described in reference to the size of the database in [/memory pages/](https://en.wikipedia.org/wiki/Page_%28computer_memory%29).
 
       [@OrdinaryIndex@]:

src/Database/LSMTree/Internal/Config.hs

@@ -54,9 +54,9 @@ A collection of configuration parameters for tables, which can be used to tune t
 
 Each parameter is associated with its own type.
 Detailed discussion of the use of each parameter can be found in the documentation for its associated type.
-These discussions may require some understanding of the internals of the LSM-tree.
+For an overview, see the [Performance](../#performance) section in the package description.
 
-The 'defaultTableConfig' defines resonable defaults for all parameters.
+The 'defaultTableConfig' defines reasonable defaults for all parameters.
 -}
 data TableConfig = TableConfig {
     -- | The merge policy determines how the table manages its data,
@@ -68,14 +68,11 @@ data TableConfig = TableConfig {
     -- | The write buffer allocation strategy determines the maximum size of the in-memory write buffer,
     --   and is the parameter \(B\) in the disk I\/O cost of operations.
     --   Irrespective of this parameter, the write buffer size cannot exceed 4GiB.
-    --   See [In-memory size of tables](../#performance_size).
   , confWriteBufferAlloc  :: !WriteBufferAlloc
     -- | The Bloom filter allocation strategy determines the number of bits per physical entry allocated for the Bloom filters.
-    --   See [In-memory size of tables](../#performance_size).
   , confBloomFilterAlloc  :: !BloomFilterAlloc
     -- | The fence pointer index type determines the type of indexes,
     --   which affects the in-memory size of the table and may constrain the table keys.
-    --   See [In-memory size of tables](../#performance_size).
   , confFencePointerIndex :: !FencePointerIndexType
     -- | The disk cache policy determines the policy for caching data from disk in memory,
     --   which may affect the performance of lookup operations.