chore(docs): revise docs related to B Plus Tree (#594)

Author: xzhseh

src/include/storage/page/b_plus_tree_header_page.h

@@ -4,6 +4,10 @@
 
 namespace bustub {
 
+/**
+ * The header page is just used to retrieve the root page,
+ * preventing potential race condition under concurrent environment.
+ */
 class BPlusTreeHeaderPage {
  public:
   // Delete all constructor / destructor to ensure memory safety

src/include/storage/page/b_plus_tree_internal_page.h

@@ -20,29 +20,30 @@ namespace bustub {
 #define B_PLUS_TREE_INTERNAL_PAGE_TYPE BPlusTreeInternalPage<KeyType, ValueType, KeyComparator>
 #define INTERNAL_PAGE_HEADER_SIZE 12
 #define INTERNAL_PAGE_SIZE ((BUSTUB_PAGE_SIZE - INTERNAL_PAGE_HEADER_SIZE) / (sizeof(MappingType)))
+
 /**
- * Store n indexed keys and n+1 child pointers (page_id) within internal page.
+ * Store `n` indexed keys and `n + 1` child pointers (page_id) within internal page.
  * Pointer PAGE_ID(i) points to a subtree in which all keys K satisfy:
  * K(i) <= K < K(i+1).
- * NOTE: since the number of keys does not equal to number of child pointers,
- * the first key always remains invalid. That is to say, any search/lookup
+ * NOTE: Since the number of keys does not equal to number of child pointers,
+ * the first key always remains invalid. That is to say, any search / lookup
  * should ignore the first key.
  *
  * Internal page format (keys are stored in increasing order):
- *  --------------------------------------------------------------------------
- * | HEADER | KEY(1)+PAGE_ID(1) | KEY(2)+PAGE_ID(2) | ... | KEY(n)+PAGE_ID(n) |
- *  --------------------------------------------------------------------------
+ * ----------------------------------------------------------------------------------
+ * | HEADER | KEY(1) + PAGE_ID(1) | KEY(2) + PAGE_ID(2) | ... | KEY(n) + PAGE_ID(n) |
+ * ----------------------------------------------------------------------------------
  */
 INDEX_TEMPLATE_ARGUMENTS
 class BPlusTreeInternalPage : public BPlusTreePage {
  public:
-  // Deleted to disallow initialization
+  // Delete all constructor / destructor to ensure memory safety
   BPlusTreeInternalPage() = delete;
   BPlusTreeInternalPage(const BPlusTreeInternalPage &other) = delete;
 
   /**
    * Writes the necessary header information to a newly created page, must be called after
-   * the creation of a new page to make a valid BPlusTreeInternalPage
+   * the creation of a new page to make a valid `BPlusTreeInternalPage`
    * @param max_size Maximal size of the page
    */
   void Init(int max_size = INTERNAL_PAGE_SIZE);
@@ -54,36 +55,34 @@ class BPlusTreeInternalPage : public BPlusTreePage {
   auto KeyAt(int index) const -> KeyType;
 
   /**
-   *
    * @param index The index of the key to set. Index must be non-zero.
    * @param key The new value for key
    */
   void SetKeyAt(int index, const KeyType &key);
 
   /**
-   *
-   * @param value the value to search for
+   * @param value The value to search for
+   * @return The index that corresponds to the specified value
    */
   auto ValueIndex(const ValueType &value) const -> int;
 
   /**
-   *
-   * @param index the index
-   * @return the value at the index
+   * @param index The index to search for
+   * @return The value at the index
    */
   auto ValueAt(int index) const -> ValueType;
 
   /**
    * @brief For test only, return a string representing all keys in
    * this internal page, formatted as "(key1,key2,key3,...)"
    *
-   * @return std::string
+   * @return The string representation of all keys in the current internal page
    */
   auto ToString() const -> std::string {
     std::string kstr = "(";
     bool first = true;
 
-    // first key of internal page is always invalid
+    // First key of internal page is always invalid
     for (int i = 1; i < GetSize(); i++) {
       KeyType key = KeyAt(i);
       if (first) {
@@ -103,4 +102,5 @@ class BPlusTreeInternalPage : public BPlusTreePage {
   // Flexible array member for page data.
   MappingType array_[0];
 };
+
 }  // namespace bustub

src/include/storage/page/b_plus_tree_leaf_page.h

@@ -23,22 +23,19 @@ namespace bustub {
 #define LEAF_PAGE_SIZE ((BUSTUB_PAGE_SIZE - LEAF_PAGE_HEADER_SIZE) / sizeof(MappingType))
 
 /**
- * Store indexed key and record id(record id = page id combined with slot id,
- * see include/common/rid.h for detailed implementation) together within leaf
+ * Store indexed key and record id (record id = page id combined with slot id,
+ * see `include/common/rid.h` for detailed implementation) together within leaf
  * page. Only support unique key.
  *
  * Leaf page format (keys are stored in order):
- *  ----------------------------------------------------------------------
- * | HEADER | KEY(1) + RID(1) | KEY(2) + RID(2) | ... | KEY(n) + RID(n)
- *  ----------------------------------------------------------------------
+ * -----------------------------------------------------------------------
+ * | HEADER | KEY(1) + RID(1) | KEY(2) + RID(2) | ... | KEY(n) + RID(n)  |
+ * -----------------------------------------------------------------------
  *
- *  Header format (size in byte, 16 bytes in total):
- *  ---------------------------------------------------------------------
- * | PageType (4) | CurrentSize (4) | MaxSize (4) |
- *  ---------------------------------------------------------------------
- *  -----------------------------------------------
- * |  NextPageId (4)
- *  -----------------------------------------------
+ * Header format (size in byte, 16 bytes in total):
+ * -----------------------------------------------------------------------
+ * | PageType (4) | CurrentSize (4) | MaxSize (4) | NextPageId (4) | ... |
+ * -----------------------------------------------------------------------
  */
 INDEX_TEMPLATE_ARGUMENTS
 class BPlusTreeLeafPage : public BPlusTreePage {
@@ -54,16 +51,16 @@ class BPlusTreeLeafPage : public BPlusTreePage {
    */
   void Init(int max_size = LEAF_PAGE_SIZE);
 
-  // helper methods
+  // Helper methods
   auto GetNextPageId() const -> page_id_t;
   void SetNextPageId(page_id_t next_page_id);
   auto KeyAt(int index) const -> KeyType;
 
   /**
-   * @brief for test only return a string representing all keys in
+   * @brief For test only return a string representing all keys in
    * this leaf page formatted as "(key1,key2,key3,...)"
    *
-   * @return std::string
+   * @return The string representation of all keys in the current internal page
    */
   auto ToString() const -> std::string {
     std::string kstr = "(";
@@ -89,4 +86,5 @@ class BPlusTreeLeafPage : public BPlusTreePage {
   // Flexible array member for page data.
   MappingType array_[0];
 };
+
 }  // namespace bustub

src/include/storage/page/b_plus_tree_page.h

@@ -34,9 +34,9 @@ enum class IndexPageType { INVALID_INDEX_PAGE = 0, LEAF_PAGE, INTERNAL_PAGE };
  * contains information shared by both leaf page and internal page.
  *
  * Header format (size in byte, 12 bytes in total):
- * ----------------------------------------------------------------------------
- * | PageType (4) | CurrentSize (4) | MaxSize (4) |
- * ----------------------------------------------------------------------------
+ * ---------------------------------------------------------
+ * | PageType (4) | CurrentSize (4) | MaxSize (4) |  ...   |
+ * ---------------------------------------------------------
  */
 class BPlusTreePage {
  public:
@@ -57,7 +57,7 @@ class BPlusTreePage {
   auto GetMinSize() const -> int;
 
  private:
-  // member variable, attributes that both internal and leaf page share
+  // Member variables, attributes that both internal and leaf page share
   IndexPageType page_type_ __attribute__((__unused__));
   int size_ __attribute__((__unused__));
   int max_size_ __attribute__((__unused__));

src/storage/index/b_plus_tree.cpp

@@ -27,6 +27,7 @@ BPLUSTREE_TYPE::BPlusTree(std::string name, page_id_t header_page_id, BufferPool
  */
 INDEX_TEMPLATE_ARGUMENTS
 auto BPLUSTREE_TYPE::IsEmpty() const -> bool { return true; }
+
 /*****************************************************************************
  * SEARCH
  *****************************************************************************/