From d937d279bd312bbbf3ab36fcfd59c73363929805 Mon Sep 17 00:00:00 2001
From: mm-near <91919554+mm-near@users.noreply.github.com>
Date: Fri, 20 Jan 2023 18:12:26 +0100
Subject: [PATCH] improved column documentation (#8414)

Co-authored-by: near-bulldozer[bot] <73298989+near-bulldozer[bot]@users.noreply.github.com>
---
 core/store/src/columns.rs | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/core/store/src/columns.rs b/core/store/src/columns.rs
index d1ab31813a8..3749e9b58f6 100644
--- a/core/store/src/columns.rs
+++ b/core/store/src/columns.rs
@@ -35,7 +35,9 @@ pub enum DBCol {
     /// - *Rows*: block hash (CryptoHash)
     /// - *Content type*: [near_primitives::block_header::BlockHeader]
     BlockHeader,
-    /// Column that stores mapping from block height to block hash.
+    /// Column that stores mapping from block height to block hash on the current canonical chain.
+    /// (if you want to see all the blocks that we got for a given height, for example due to double signing etc,
+    /// look at BlockPerHeight column).
     /// - *Rows*: height (u64)
     /// - *Content type*: block hash (CryptoHash)
     BlockHeight,
@@ -105,6 +107,8 @@ pub enum DBCol {
     /// - *Content type*: BlockExtra
     BlockExtra,
     /// Store hash of all block per each height, to detect double signs.
+    /// In most cases, it is better to get the value from BlockHeight column instead (which
+    /// keeps the hash of the block from canonical chain)
     /// - *Rows*: int (height of the block)
     /// - *Content type*: Map: EpochId -> Set of BlockHash(CryptoHash)
     BlockPerHeight,
@@ -180,7 +184,12 @@ pub enum DBCol {
     /// - *Rows*: BlockHash || TrieKey (TrieKey is written via custom to_vec)
     /// - *Column type*: TrieKey, new value and reason for change (RawStateChangesWithTrieKey)
     StateChanges,
-    /// Mapping from Block to its refcount. (Refcounts are used in handling chain forks)
+    /// Mapping from Block to its refcount (number of blocks that use this block as a parent). (Refcounts are used in handling chain forks).
+    /// In following example:
+    ///     1 -> 2 -> 3 -> 5
+    ///           \ --> 4
+    /// The block '2' will have a refcount equal to 2.
+    ///
     /// - *Rows*: BlockHash (CryptoHash)
     /// - *Column type*: refcount (u64)
     BlockRefCount,
@@ -197,6 +206,8 @@ pub enum DBCol {
     /// - *Column type*: Vec<ChunkHash (CryptoHash)>
     ChunkHashesByHeight,
     /// Mapping from block ordinal number (number of the block in the chain) to the BlockHash.
+    /// Note: that it can be different than BlockHeight - if we have skipped some heights when creating the blocks.
+    ///       for example in chain 1->3, the second block has height 3, but ordinal 2.
     /// - *Rows*: ordinal (u64)
     /// - *Column type*: BlockHash (CryptoHash)
     BlockOrdinal,