move doc comments from headers to source files

src/binder/binder.cpp

@@ -42,6 +42,9 @@ namespace bustub {
 
 Binder::Binder(const Catalog &catalog) : catalog_(catalog) {}
 
+/** Attempts to parse a query into a series of SQL statements. The parsed statements
+ * will be stored in the `statements_nodes_` variable.
+ */
 void Binder::ParseAndSave(const std::string &query) {
   parser_.Parse(query);
   if (!parser_.success) {
@@ -58,8 +61,10 @@ void Binder::ParseAndSave(const std::string &query) {
   SaveParseTree(parser_.parse_tree);
 }
 
+/** Return true if the given text matches a keyword of the parser. */
 auto Binder::IsKeyword(const std::string &text) -> bool { return duckdb::PostgresParser::IsKeyword(text); }
 
+/** Return a list of all keywords in the parser. */
 auto Binder::KeywordList() -> std::vector<ParserKeyword> {
   auto keywords = duckdb::PostgresParser::KeywordList();
   std::vector<ParserKeyword> result;
@@ -87,6 +92,7 @@ auto Binder::KeywordList() -> std::vector<ParserKeyword> {
   return result;
 }
 
+/** Tokenize a query, returning the raw tokens together with their locations. */
 auto Binder::Tokenize(const std::string &query) -> std::vector<SimplifiedToken> {
   auto pg_tokens = duckdb::PostgresParser::Tokenize(query);
   std::vector<SimplifiedToken> result;

src/binder/keyword_helper.cpp

@@ -26,8 +26,10 @@
 
 namespace bustub {
 
+/** Return true if the given text matches a keyword of the parser. */
 auto KeywordHelper::IsKeyword(const std::string &text) -> bool { return Binder::IsKeyword(text); }
 
+/** Return true if the given std::string needs to be quoted when written as an identifier. */
 auto KeywordHelper::RequiresQuotes(const std::string &text) -> bool {
   for (size_t i = 0; i < text.size(); i++) {
     if (i > 0 && (text[i] >= '0' && text[i] <= '9')) {
@@ -44,6 +46,7 @@ auto KeywordHelper::RequiresQuotes(const std::string &text) -> bool {
   return IsKeyword(text);
 }
 
+/** Writes a std::string that is optionally quoted + escaped so it can be used as an identifier */
 auto KeywordHelper::WriteOptionallyQuoted(const std::string &text, char quote) -> std::string {
   if (!RequiresQuotes(text)) {
     return text;

src/binder/node_tag_to_string.cpp

@@ -25,6 +25,7 @@
 
 namespace bustub {
 
+/** Get the std::string representation of a Postgres node tag. */
 auto Binder::NodeTagToString(duckdb_libpgquery::PGNodeTag type) -> std::string {
   switch (type) {
     case duckdb_libpgquery::T_PGInvalid:

src/binder/transformer.cpp

@@ -43,13 +43,15 @@
 
 namespace bustub {
 
+/** Transform a Postgres parse tree into a std::vector of SQL Statements. */
 void Binder::SaveParseTree(duckdb_libpgquery::PGList *tree) {
   std::vector<std::unique_ptr<BoundStatement>> statements;
   for (auto entry = tree->head; entry != nullptr; entry = entry->next) {
     statement_nodes_.push_back(reinterpret_cast<duckdb_libpgquery::PGNode *>(entry->data.ptr_value));
   }
 }
 
+/** Transform a Postgres statement into a single SQL statement. */
 auto Binder::BindStatement(duckdb_libpgquery::PGNode *stmt) -> std::unique_ptr<BoundStatement> {
   switch (stmt->type) {
     case duckdb_libpgquery::T_PGRawStmt:

src/buffer/clock_replacer.cpp

@@ -14,8 +14,15 @@
 
 namespace bustub {
 
+/**
+ * Create a new ClockReplacer.
+ * @param num_pages the maximum number of pages the ClockReplacer will be required to store
+ */
 ClockReplacer::ClockReplacer(size_t num_pages) {}
 
+/**
+ * Destroys the ClockReplacer.
+ */
 ClockReplacer::~ClockReplacer() = default;
 
 auto ClockReplacer::Victim(frame_id_t *frame_id) -> bool { return false; }

src/buffer/lru_k_replacer.cpp

@@ -15,16 +15,92 @@
 
 namespace bustub {
 
+/**
+ *
+ * TODO(P1): Add implementation
+ *
+ * @brief a new LRUKReplacer.
+ * @param num_frames the maximum number of frames the LRUReplacer will be required to store
+ */
 LRUKReplacer::LRUKReplacer(size_t num_frames, size_t k) : replacer_size_(num_frames), k_(k) {}
 
+/**
+ * TODO(P1): Add implementation
+ *
+ * @brief Find the frame with largest backward k-distance and evict that frame. Only frames
+ * that are marked as 'evictable' are candidates for eviction.
+ *
+ * A frame with less than k historical references is given +inf as its backward k-distance.
+ * If multiple frames have inf backward k-distance, then evict frame whose oldest timestamp
+ * is furthest in the past.
+ *
+ * Successful eviction of a frame should decrement the size of replacer and remove the frame's
+ * access history.
+ *
+ * @return true if a frame is evicted successfully, false if no frames can be evicted.
+ */
 auto LRUKReplacer::Evict() -> std::optional<frame_id_t> { return std::nullopt; }
 
+/**
+ * TODO(P1): Add implementation
+ *
+ * @brief Record the event that the given frame id is accessed at current timestamp.
+ * Create a new entry for access history if frame id has not been seen before.
+ *
+ * If frame id is invalid (ie. larger than replacer_size_), throw an exception. You can
+ * also use BUSTUB_ASSERT to abort the process if frame id is invalid.
+ *
+ * @param frame_id id of frame that received a new access.
+ * @param access_type type of access that was received. This parameter is only needed for
+ * leaderboard tests.
+ */
 void LRUKReplacer::RecordAccess(frame_id_t frame_id, [[maybe_unused]] AccessType access_type) {}
 
+/**
+ * TODO(P1): Add implementation
+ *
+ * @brief Toggle whether a frame is evictable or non-evictable. This function also
+ * controls replacer's size. Note that size is equal to number of evictable entries.
+ *
+ * If a frame was previously evictable and is to be set to non-evictable, then size should
+ * decrement. If a frame was previously non-evictable and is to be set to evictable,
+ * then size should increment.
+ *
+ * If frame id is invalid, throw an exception or abort the process.
+ *
+ * For other scenarios, this function should terminate without modifying anything.
+ *
+ * @param frame_id id of frame whose 'evictable' status will be modified
+ * @param set_evictable whether the given frame is evictable or not
+ */
 void LRUKReplacer::SetEvictable(frame_id_t frame_id, bool set_evictable) {}
 
+/**
+ * TODO(P1): Add implementation
+ *
+ * @brief Remove an evictable frame from replacer, along with its access history.
+ * This function should also decrement replacer's size if removal is successful.
+ *
+ * Note that this is different from evicting a frame, which always remove the frame
+ * with largest backward k-distance. This function removes specified frame id,
+ * no matter what its backward k-distance is.
+ *
+ * If Remove is called on a non-evictable frame, throw an exception or abort the
+ * process.
+ *
+ * If specified frame is not found, directly return from this function.
+ *
+ * @param frame_id id of frame to be removed
+ */
 void LRUKReplacer::Remove(frame_id_t frame_id) {}
 
+/**
+ * TODO(P1): Add implementation
+ *
+ * @brief Return replacer's size, which tracks the number of evictable frames.
+ *
+ * @return size_t
+ */
 auto LRUKReplacer::Size() -> size_t { return 0; }
 
 }  // namespace bustub

src/buffer/lru_replacer.cpp

@@ -14,8 +14,15 @@
 
 namespace bustub {
 
+/**
+ * Create a new LRUReplacer.
+ * @param num_pages the maximum number of pages the LRUReplacer will be required to store
+ */
 LRUReplacer::LRUReplacer(size_t num_pages) {}
 
+/**
+ * Destroys the LRUReplacer.
+ */
 LRUReplacer::~LRUReplacer() = default;
 
 auto LRUReplacer::Victim(frame_id_t *frame_id) -> bool { return false; }

src/catalog/column.cpp

@@ -18,6 +18,7 @@
 
 namespace bustub {
 
+/** @return a string representation of this column */
 auto Column::ToString(bool simplified) const -> std::string {
   if (simplified) {
     std::ostringstream os;

src/catalog/schema.cpp

@@ -18,6 +18,10 @@
 
 namespace bustub {
 
+/**
+ * Constructs the schema corresponding to the vector of columns, read left-to-right.
+ * @param columns columns that describe the schema's individual columns
+ */
 Schema::Schema(const std::vector<Column> &columns) {
   uint32_t curr_offset = 0;
   for (uint32_t index = 0; index < columns.size(); index++) {
@@ -42,6 +46,7 @@ Schema::Schema(const std::vector<Column> &columns) {
   length_ = curr_offset;
 }
 
+/** @return string representation of this schema */
 auto Schema::ToString(bool simplified) const -> std::string {
   if (simplified) {
     std::ostringstream os;

src/catalog/table_generator.cpp

@@ -84,6 +84,9 @@ void TableGenerator::FillTable(const std::shared_ptr<TableInfo> &info, TableInse
   }
 }
 
+/**
+ * Generate test tables.
+ */
 void TableGenerator::GenerateTestTables() {
   /**
    * This array configures each of the test tables. Each table is configured

src/common/bustub_instance.cpp

@@ -40,6 +40,9 @@
 
 namespace bustub {
 
+/**
+ * Get the executor context from the BusTub instance.
+ */
 auto BusTubInstance::MakeExecutorContext(Transaction *txn, bool is_modify) -> std::unique_ptr<ExecutorContext> {
   return std::make_unique<ExecutorContext>(txn, catalog_.get(), buffer_pool_manager_.get(), txn_manager_.get(),
                                            lock_manager_.get(), is_modify);
@@ -231,6 +234,9 @@ see the execution plan of your query.
   WriteOneCell(help, writer);
 }
 
+/**
+ * Execute a SQL query in the BusTub instance.
+ */
 auto BusTubInstance::ExecuteSql(const std::string &sql, ResultWriter &writer,
                                 std::shared_ptr<CheckOptions> check_options) -> bool {
   bool is_local_txn = current_txn_ != nullptr;
@@ -251,6 +257,9 @@ auto BusTubInstance::ExecuteSql(const std::string &sql, ResultWriter &writer,
   }
 }
 
+/**
+ * Execute a SQL query in the BusTub instance with provided txn.
+ */
 auto BusTubInstance::ExecuteSqlTxn(const std::string &sql, ResultWriter &writer, Transaction *txn,
                                    std::shared_ptr<CheckOptions> check_options) -> bool {
   if (!sql.empty() && sql[0] == '\\') {