Renamed SqlDocs to SqlFileDoc for disambiguation. Fixes #17

Author: RPG-Alex

proposed_mods.md

@@ -3,6 +3,6 @@
 sql_docs:
     builder for 
     ```rust
-    SqlDocs
+    SqlFileDoc
     ```
 

src/docs.rs

@@ -91,12 +91,12 @@ impl TableDoc {
 /// Structure for containing the docs for every `Table` in an `.sql` file as a
 /// `Vec` of [`TableDoc`]
 #[derive(Clone, Debug, Eq, PartialEq)]
-pub struct SqlDocs {
+pub struct SqlFileDoc {
     tables: Vec<TableDoc>,
 }
 
-impl SqlDocs {
-    /// Create a new instance of [`SqlDocs`]
+impl SqlFileDoc {
+    /// Create a new instance of [`SqlFileDoc`]
     ///
     /// # Parameters
     /// - `tables` the `Vec` of [`TableDoc`] for the struct
@@ -200,7 +200,7 @@ fn schema_and_table(name: &ObjectName) -> Result<(Option<String>, String), DocEr
 
 #[cfg(test)]
 mod tests {
-    use crate::docs::{ColumnDoc, SqlDocs, TableDoc};
+    use crate::docs::{ColumnDoc, SqlFileDoc, TableDoc};
 
     #[test]
     fn test_sql_docs_struct() {
@@ -213,7 +213,7 @@ mod tests {
             columns,
         );
         let tables = vec![table_doc];
-        let sql_doc = SqlDocs::new(tables);
+        let sql_doc = SqlFileDoc::new(tables);
         let sql_doc_val =
             sql_doc.tables().first().map_or_else(|| panic!("unable to find tables"), |val| val);
         assert_eq!(sql_doc_val.name(), "user");
@@ -235,7 +235,7 @@ mod tests {
 
         for file in parsed_set.files() {
             let comments = Comments::parse_all_comments_from_file(file)?;
-            let docs = SqlDocs::from_parsed_file(file, &comments);
+            let docs = SqlFileDoc::from_parsed_file(file, &comments);
             let filename = file
                 .file()
                 .path()
@@ -265,8 +265,8 @@ mod tests {
         Ok(())
     }
 
-    fn expected_without_comments_docs() -> SqlDocs {
-        SqlDocs::new(vec![
+    fn expected_without_comments_docs() -> SqlFileDoc {
+        SqlFileDoc::new(vec![
             TableDoc::new(
                 None,
                 "users".to_string(),
@@ -293,10 +293,10 @@ mod tests {
         ])
     }
 
-    fn expect_values() -> Vec<SqlDocs> {
+    fn expect_values() -> Vec<SqlFileDoc> {
         let mut docs = Vec::new();
 
-        let first_docs = SqlDocs::new(vec![
+        let first_docs = SqlFileDoc::new(vec![
             TableDoc::new(
                 None,
                 "users".to_string(),
@@ -332,7 +332,7 @@ mod tests {
         ]);
         docs.push(first_docs);
 
-        let second_docs = SqlDocs::new(vec![
+        let second_docs = SqlFileDoc::new(vec![
             TableDoc::new(
                 None,
                 "users".to_string(),

src/lib.rs

@@ -4,16 +4,18 @@
 //! - [`ast`]      : parse SQL into an AST using [`sqlparser`]
 //! - [`comments`] : extract and model comments and spans
 
-use crate::{ast::ParsedSqlFileSet, comments::Comments, docs::SqlDocs, files::SqlFileSet};
+use crate::{ast::ParsedSqlFileSet, comments::Comments, docs::SqlFileDoc, files::SqlFileSet};
 pub use error::DocError;
 use std::path::{Path, PathBuf};
 pub mod ast;
 pub mod comments;
 pub mod docs;
 pub mod error;
 pub mod files;
+mod sql_doc;
+pub use sql_doc::SqlDoc;
 
-/// Primary Entry point. Returns a tuple of [`PathBuf`] and [`SqlDocs`].
+/// Primary Entry point. Returns a tuple of [`PathBuf`] and [`SqlFileDoc`].
 ///
 /// # Parameters:
 /// - `dir`: the [`Path`] to recursively parse `.sql` files. Allows for coercion
@@ -33,7 +35,7 @@ pub mod files;
 pub fn generate_docs_from_dir<P: AsRef<Path>, S: AsRef<str>>(
     dir: P,
     deny_list: &[S],
-) -> Result<Vec<(PathBuf, SqlDocs)>, DocError> {
+) -> Result<Vec<(PathBuf, SqlFileDoc)>, DocError> {
     // Convert deny list to a `Vec<String>`
     let deny_vec: Vec<String> = deny_list.iter().map(|file| file.as_ref().to_string()).collect();
     // verify whether deny_list is empty and return correct `Option`
@@ -43,17 +45,17 @@ pub fn generate_docs_from_dir<P: AsRef<Path>, S: AsRef<str>>(
     // parse all files sql
     let parsed_files = ParsedSqlFileSet::parse_all(file_set)?;
     let mut sql_docs = Vec::new();
-    // iterate on each file and generate the `SqlDocs` and associate with the `Path`
+    // iterate on each file and generate the `SqlFileDoc` and associate with the `Path`
     for file in parsed_files.files() {
         let comments = Comments::parse_all_comments_from_file(file)?;
-        let docs = SqlDocs::from_parsed_file(file, &comments)?;
+        let docs = SqlFileDoc::from_parsed_file(file, &comments)?;
         let path = file.file().path().to_path_buf();
         sql_docs.push((path, docs));
     }
     Ok(sql_docs)
 }
 
-/// Secondary Entry point. Returns a tuple of [`PathBuf`] and [`SqlDocs`].
+/// Secondary Entry point. Returns a tuple of [`PathBuf`] and [`SqlFileDoc`].
 /// Useful when no deny list is needed
 ///
 /// # Parameters:
@@ -71,7 +73,7 @@ pub fn generate_docs_from_dir<P: AsRef<Path>, S: AsRef<str>>(
 /// ```
 pub fn generate_docs_from_dir_no_deny<P: AsRef<Path>>(
     dir: P,
-) -> Result<Vec<(PathBuf, SqlDocs)>, DocError> {
+) -> Result<Vec<(PathBuf, SqlFileDoc)>, DocError> {
     generate_docs_from_dir::<P, &str>(dir, &[])
 }
 
@@ -109,7 +111,7 @@ mod tests {
             let parsed_doc_table_doc = parsed_doc.tables()[i]
                 .doc()
                 .as_ref()
-                .map_or_else(|| panic!("unable to find SqlDocs table doc"), |val| val);
+                .map_or_else(|| panic!("unable to find SqlFileDoc table doc"), |val| val);
             assert_eq!(parsed_doc_table_doc, table_comments[i]);
         }
         let user_columns = ["id", "username", "email", "created_at"];

src/sql_doc.rs

@@ -0,0 +1,66 @@
+//! Module for the top level `SqlDoc` structure. 
+
+use std::path::{Path, PathBuf};
+
+use crate::{
+    ast::ParsedSqlFileSet,
+    comments::Comments,
+    docs::{SqlFileDoc, TableDoc, ColumnDoc},
+    error::DocError,
+    files::SqlFileSet,
+};
+
+pub struct SqlDoc {
+    // e.g. all tables across all files
+    tables: Vec<TableDoc>,           // or a map keyed by (schema, name)
+    // optionally: keep per-file docs too
+    files: Vec<(PathBuf, SqlFileDoc)>,
+}
+
+pub struct SqlDocBuilder {
+    source: SqlFileDocource,
+    deny: Vec<String>,
+}
+
+enum SqlFileDocource {
+    Dir(PathBuf),
+    File(PathBuf),
+}
+
+impl SqlDoc {
+    pub fn from_dir<P: AsRef<Path>>(root: P) -> SqlDocBuilder {
+        SqlDocBuilder {
+            source: SqlFileDocource::Dir(root.as_ref().to_path_buf()),
+            deny: Vec::new(),
+        }
+    }
+
+    pub fn from_path<P: AsRef<Path>>(path: P) -> SqlDocBuilder {
+        SqlDocBuilder {
+            source: SqlFileDocource::File(path.as_ref().to_path_buf()),
+            deny: Vec::new(),
+        }
+    }
+
+    // later:
+    // pub fn table(&self, name: &str) -> Result<&TableDoc, DocError> { ... }
+    // pub fn table_with_schema(&self, schema: &str, name: &str) -> Result<&TableDoc, DocError> { ... }
+}
+
+impl SqlDocBuilder {
+    pub fn deny<S: AsRef<str>>(mut self, pattern: S) -> Self {
+        self.deny.push(pattern.as_ref().to_string());
+        self
+    }
+
+    pub fn build(self) -> Result<SqlDoc, DocError> {
+        match self.source {
+            SqlFileDocource::Dir(root) => {
+                // Use your existing directory logic here
+            }
+            SqlFileDocource::File(path) => {
+                // Same plumbing but for a single file
+            }
+        }
+    }
+}