From a4afadfd2ea6d8ba8fc4e5c6b0fcaa8a0adbc5e3 Mon Sep 17 00:00:00 2001
From: Pekka Enberg <penberg@iki.fi>
Date: Thu, 25 Jul 2024 17:32:50 +0300
Subject: [PATCH] core: Select struct documentation

---
 core/translate/select.rs | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/core/translate/select.rs b/core/translate/select.rs
index 301b4beef..a40813fdc 100644
--- a/core/translate/select.rs
+++ b/core/translate/select.rs
@@ -19,23 +19,35 @@ use crate::{function::Func, schema::Table, vdbe::BranchOffset};
 
 use super::SortInfo;
 
+/// A representation of a `SELECT` statement that has all the information
+/// needed for code generation.
 pub struct Select<'a> {
+    /// The columns that are being selected.
     pub columns: &'a Vec<ast::ResultColumn>,
+    /// Information about each column.
     pub column_info: Vec<ColumnInfo<'a>>,
-    pub src_tables: Vec<SrcTable<'a>>, // Tables we use to get data from. This includes "from" and "joins"
+    /// The tables we are retrieving data from, including tables mentioned
+    /// in `FROM` and `JOIN` clauses.
+    pub src_tables: Vec<SrcTable<'a>>,
+    /// The `LIMIT` clause.
     pub limit: &'a Option<ast::Limit>,
+    /// The `ORDER BY` clause.
     pub order_by: &'a Option<Vec<ast::SortedColumn>>,
+    /// Whether the query contains an aggregation function.
     pub exist_aggregation: bool,
+    /// The `WHERE` clause.
     pub where_clause: &'a Option<ast::Expr>,
-    /// Ordered list of opened read table loops
-    /// Used for generating a loop that looks like this:
-    /// cursor 0 = open table 0
-    /// for each row in cursor 0
-    ///     cursor 1 = open table 1
-    ///     for each row in cursor 1
-    ///         ...
-    ///     end cursor 1
-    /// end cursor 0
+    /// Ordered list of opened read table loops.
+    ///
+    /// The list is used to generate inner loops like this:
+    ///
+    ///   cursor 0 = open table 0
+    ///   for each row in cursor 0
+    ///       cursor 1 = open table 1
+    ///       for each row in cursor 1
+    ///           ...
+    ///       end cursor 1
+    ///   end cursor 0
     pub loops: Vec<LoopInfo>,
 }