Improve comments of classes for PlainTable (#5339)

Summary:
Simply add some comments.
Pull Request resolved: https://github.com/facebook/rocksdb/pull/5339

Differential Revision: D15485315

Pulled By: siying

fbshipit-source-id: 4594b1c4c967e6bd08aa7fa08a37df3481df1938

table/plain_table_builder.h

@@ -24,6 +24,9 @@ class BlockHandle;
 class WritableFile;
 class TableBuilder;
 
+// The builder class of PlainTable. For description of PlainTable format
+// See comments of class PlainTableFactory, where instances of
+// PlainTableReader are created.
 class PlainTableBuilder: public TableBuilder {
  public:
   // Create a builder that will store the contents of the table it is

table/plain_table_factory.h

@@ -24,7 +24,19 @@ class WritableFile;
 class Table;
 class TableBuilder;
 
-// IndexedTable requires fixed length key, configured as a constructor
+// PlainTableFactory is the entrance function to the PlainTable format of
+// SST files. It returns instances PlainTableBuilder as the builder
+// class and PlainTableReader as the reader class, where the format is
+// actually implemented.
+//
+// The PlainTable is designed for memory-mapped file systems, e.g. tmpfs.
+// Data is not organized in blocks, which allows fast access. Because of
+// following downsides
+// 1. Data compression is not supported.
+// 2. Data is not checksumed.
+// it is not recommended to use this format on other type of file systems.
+// 
+// PlainTable requires fixed length key, configured as a constructor
 // parameter of the factory class. Output file format:
 // +-------------+-----------------+
 // | version     | user_key_length |

table/plain_table_index.h

@@ -20,6 +20,12 @@
 
 namespace rocksdb {
 
+// The file contains two classes PlainTableIndex and PlainTableIndexBuilder
+// The two classes implement the index format of PlainTable.
+// For descripton of PlainTable format, see comments of class
+// PlainTableFactory
+//
+//
 // PlainTableIndex contains buckets size of index_size_, each is a
 // 32-bit integer. The lower 31 bits contain an offset value (explained below)
 // and the first bit of the integer indicates type of the offset.
@@ -55,6 +61,10 @@ namespace rocksdb {
 //    ....
 //   record N file offset:  fixedint32
 // <end>
+
+// The class loads the index block from a PlainTable SST file, and executes
+// the index lookup.
+// The class is used by PlainTableReader class.
 class PlainTableIndex {
  public:
   enum IndexSearchResult {
@@ -72,11 +82,22 @@ class PlainTableIndex {
         index_(nullptr),
         sub_index_(nullptr) {}
 
+  // The function that executes the lookup the hash table.
+  // The hash key is `prefix_hash`. The function fills the hash bucket
+  // content in `bucket_value`, which is up to the caller to interpret.
   IndexSearchResult GetOffset(uint32_t prefix_hash,
                               uint32_t* bucket_value) const;
 
-  Status InitFromRawData(Slice data);
+  // Initialize data from `index_data`, which points to raw data for
+  // index stored in the SST file.
+  Status InitFromRawData(Slice index_data);
 
+  // Decode the sub index for specific hash bucket.
+  // The `offset` is the value returned as `bucket_value` by GetOffset()
+  // and is only valid when the return value is `kSubindex`.
+  // The return value is the pointer to the starting address of the
+  // sub-index. `upper_bound` is filled with the value indicating how many
+  // entries the sub-index has.
   const char* GetSubIndexBasePtrAndUpperBound(uint32_t offset,
                                               uint32_t* upper_bound) const {
     const char* index_ptr = &sub_index_[offset];
@@ -106,9 +127,10 @@ class PlainTableIndex {
 // After calling Finish(), it returns Slice, which is usually
 // used either to initialize PlainTableIndex or
 // to save index to sst file.
-// For more details about the  index, please refer to:
+// For more details about the index, please refer to:
 // https://github.com/facebook/rocksdb/wiki/PlainTable-Format
 // #wiki-in-memory-index-format
+// The class is used by PlainTableBuilder class.
 class PlainTableIndexBuilder {
  public:
   PlainTableIndexBuilder(Arena* arena, const ImmutableCFOptions& ioptions,

table/plain_table_key_coding.h

@@ -11,6 +11,11 @@
 #include "db/dbformat.h"
 #include "table/plain_table_reader.h"
 
+// The file contains three helper classes of PlainTable format,
+// PlainTableKeyEncoder, PlainTableKeyDecoder and PlainTableFileReader.
+// These classes issue the lowest level of operations of PlainTable.
+// Actual data format of the key is documented in comments of class
+// PlainTableFactory.
 namespace rocksdb {
 
 class WritableFile;
@@ -18,8 +23,8 @@ struct ParsedInternalKey;
 struct PlainTableReaderFileInfo;
 enum PlainTableEntryType : unsigned char;
 
-// Helper class to write out a key to an output file
+// Helper class for PlainTable format to write out a key to an output file
-// Actual data format of the key is documented in plain_table_factory.h
+// The class is used in PlainTableBuilder.
 class PlainTableKeyEncoder {
  public:
   explicit PlainTableKeyEncoder(EncodingType encoding_type,
@@ -53,6 +58,10 @@ class PlainTableKeyEncoder {
   IterKey pre_prefix_;
 };
 
+// The class does raw file reads for PlainTableReader.
+// It hides whether it is a mmap-read, or a non-mmap read.
+// The class is implemented in a way to favor the performance of mmap case.
+// The class is used by PlainTableReader.
 class PlainTableFileReader {
  public:
   explicit PlainTableFileReader(const PlainTableReaderFileInfo* _file_info)
@@ -122,7 +131,7 @@ class PlainTableFileReader {
 };
 
 // A helper class to decode keys from input buffer
-// Actual data format of the key is documented in plain_table_factory.h
+// The class is used by PlainTableBuilder.
 class PlainTableKeyDecoder {
  public:
   explicit PlainTableKeyDecoder(const PlainTableReaderFileInfo* file_info,

table/plain_table_reader.h

@@ -56,16 +56,17 @@ struct PlainTableReaderFileInfo {
         file(std::move(_file)) {}
 };
 
+// The reader class of PlainTable. For description of PlainTable format
+// See comments of class PlainTableFactory, where instances of
+// PlainTableReader are created.
+class PlainTableReader: public TableReader {
+ public:
 // Based on following output file format shown in plain_table_factory.h
-// When opening the output file, IndexedTableReader creates a hash table
+// When opening the output file, PlainTableReader creates a hash table
-// from key prefixes to offset of the output file. IndexedTable will decide
+// from key prefixes to offset of the output file. PlainTable will decide
 // whether it points to the data offset of the first key with the key prefix
 // or the offset of it. If there are too many keys share this prefix, it will
 // create a binary search-able index from the suffix to offset on disk.
-//
-// The implementation of IndexedTableReader requires output file is mmaped
-class PlainTableReader: public TableReader {
- public:
   static Status Open(const ImmutableCFOptions& ioptions,
                      const EnvOptions& env_options,
                      const InternalKeyComparator& internal_comparator,