final polish for 1.0 release

Author: RPG-Alex

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "sql_docs"
-version = "0.1.0"
+version = "1.0.0"
 edition = "2024"
 description = "A crate for parsing comments from sql files and using them for documentation generation"
 license = "GNU General Public License v3.0"

Cargo.toml

@@ -3,13 +3,13 @@
 [![License](https://img.shields.io/badge/GPL-3%20-blue.svg)](https://opensource.org/license/gpl-3-0)
 [![Codecov](https://codecov.io/gh/rpg-alex/sql-docs/branch/main/graph/badge.svg)](https://codecov.io/gh/rpg-alex)
 
-This crate extracts *documentation* from SQL files by parsing:
+This crate extracts **documentation** from SQL files by parsing:
 
-- SQL statements (via [DataFusion’s SQL Parser](https://github.com/apache/datafusion-sqlparser-rs/))
-- Inline and multiline comments
+- SQL statements (via [`sqlparser`](https://github.com/sqlparser-rs/sqlparser-rs))
+- Line and block comments
 - Table and column locations
 
-It then attaches comments to the SQL structures they describe.
+It then attaches comments to the SQL structures they describe, producing a structured, queryable documentation model.
 
 ## Example 
 
@@ -34,46 +34,76 @@ A rudimentary implementation can be generated with:
 ```rust
 use sql_docs::SqlDoc;
 use sql_docs::error::DocError;
-use std::{env, fs, path::Path};
+use std::{env, fs};
 
 fn main() -> Result<(), DocError> {
-    // tmp dir and file created for demonstration purposes
+    // Temporary directory and file created for demonstration purposes
     let base = env::temp_dir().join("tmp_dir");
     let _ = fs::remove_dir_all(&base);
     fs::create_dir_all(&base)?;
     let example = base.join("example.sql");
-    fs::write(&example, r#"/* Table storing user accounts */
-    CREATE TABLE users (
-        /* Primary key for each user */
-        id INTEGER PRIMARY KEY,
-        -- The user's login name
-        username VARCHAR(255) NOT NULL,
-        /* User's email address */
-        email VARCHAR(255) UNIQUE NOT NULL
-    );"#)?;
-
-    // Extract table & column documentation
+
+    fs::write(
+        &example,
+        r#"/* Table storing user accounts */
+CREATE TABLE users (
+    /* Primary key for each user */
+    id INTEGER PRIMARY KEY,
+    -- The user's login name
+    username VARCHAR(255) NOT NULL,
+    /* User's email address */
+    email VARCHAR(255) UNIQUE NOT NULL
+);"#,
+    )?;
+
+    // Extract documentation from a single file
     let docs = SqlDoc::from_path(&example).build()?;
-    // Verify that the table name is correct
-    assert_eq!(docs.tables().first().expect("hardcoded value").name(), "users");
-    // Verify extraction of table comment
-    assert_eq!(docs.tables().first().expect("hardcoded value").doc(), Some("Table storing user accounts"));
-    // Verify First Column name and comment
-    assert_eq!(docs.tables().first().expect("hardcoded value").columns().first().expect("hardcoded value").name(), "id");
-    assert_eq!(docs.tables().first().expect("hardcoded value").columns().first().expect("hardcoded value").doc(), Some("Primary key for each user"));
+    // Or extract recursively from a directory
+    // let docs = SqlDoc::from_dir(&base).build()?;
+
+    // Retrieve a specific table
+    let users = docs.table("users")?;
+
+    // Table name
+    assert_eq!(users.name(), "users");
+    // Optional table-level documentation
+    assert_eq!(users.doc(), Some("Table storing user accounts"));
+    // Path to the source file
+    assert_eq!(users.path(), &Some(example));
+
     let _ = fs::remove_dir_all(&base);
     Ok(())
 }
 ```
-## Use cases
+## Primary Interface (Main API)
+
+These are the primary entry points most users will interact with:
+
+* [`SqlDoc::from_path`](https://docs.rs/sql-docs/latest/sql_docs/sql_doc/struct.SqlDoc.html#method.from_path) Build documentation from a single `.sql` file.
+* [`SqlDoc::from_dir`](https://docs.rs/sql-docs/latest/sql_docs/sql_doc/struct.SqlDoc.html#method.from_dir) Recursively scan a directory for `.sql` files and build documentation.
+* [`SqlDocBuilder::build`](https://docs.rs/sql-docs/latest/sql_docs/sql_doc/struct.SqlDocBuilder.html#method.build) Finalize the builder and produce a [`SqlDoc`].
+* [`SqlDocBuilder::deny`](https://docs.rs/sql-docs/latest/sql_docs/sql_doc/struct.SqlDocBuilder.html#method.deny) Exclude specific files by full path.
+* [`SqlDocBuilder::flatten_multiline`](https://docs.rs/sql-docs/latest/sql_docs/sql_doc/struct.SqlDocBuilder.html#method.flatten_multiline) Flatten multiline comments into a single line.
+
+## Use Cases
 
 This crate is designed for generating documentation from SQL schemas by attaching comments to:
-- Tables
-- Columns
 
-using only comments that immediately precede the items they describe.
+* Tables
+* Columns
+
+using **only comments that immediately precede** the items they describe.
+
+This makes it well-suited for:
+
+* Auto-generating Markdown or HTML documentation
+* Building database schema explorers
+* Enforcing documentation rules in CI
+* Static analysis of SQL schemas
+
+## Design Notes
 
-This makes it ideal for:
-- Auto-generating Markdown or HTML documentation
-- Building database schema explorers
-- Enforcing documentation rules in CI
+* Inline and interstitial comments are intentionally ignored.
+* Comment attachment is line-based and deterministic.
+* One SQL file may define multiple tables.
+* No database connection is required.

README.md

@@ -1,5 +1,7 @@
-//! Module for parsing the SQL and then using the resulting AST that will later
-//! be used in `comments` module
+//! Parse SQL text into an AST (`sqlparser`) for downstream comment attachment.
+//!
+//! This module does not interpret semantics; it only produces an AST + file metadata.
+
 use std::path::{Path, PathBuf};
 
 use sqlparser::{
@@ -17,17 +19,16 @@ pub struct ParsedSqlFile {
 }
 
 impl ParsedSqlFile {
-    /// A parsed SQL file containing `DataFusion` AST nodes paired with their
-    /// spans.
+    /// Parses a [`SqlFile`] into `sqlparser` [`Statement`] nodes.
     ///
-    /// This struct wraps DataFusion’s `Statement` parsing so we can attach
-    /// leading comments later in the pipeline.
+    /// This is the AST layer used by the `comments` module to attach leading
+    /// comment spans to statements/columns.
     ///
     /// # Parameters
-    /// - `file` is the [`SqlFile`] that will be parsed
+    /// - `file`: the [`SqlFile`] to parse
     ///
     /// # Errors
-    /// - [`ParserError`] is returned for any errors parsing
+    /// - Returns [`ParserError`] if parsing fails
     pub fn parse(file: SqlFile) -> Result<Self, ParserError> {
         let dialect = GenericDialect {};
         let statements = Parser::parse_sql(&dialect, file.content())?;

src/ast.rs

@@ -1,14 +1,15 @@
-//! Module for crawling the SQL documents based on the parser and
-//! parsing/extracting the leading comments.
+//! Extract comment spans from parsed SQL files.
 //!
-//! *leading comment* a comment that
-//! precedes an SQL Statement.
+//! Definitions used throughout this crate:
+//! - **leading**: a comment that appears on lines immediately preceding a statement/column
+//! - **inline**: a comment that appears after code on the same line (ignored)
+//! - **interstitial**: a comment inside a statement (ignored)
+
 use std::fmt;
 
 use crate::ast::ParsedSqlFile;
 
-/// Structure for holding a location in the file. Assumes file is first split by
-/// lines and then split by characters (column)
+/// Represents a line/column location within a source file.
 #[derive(Clone, Debug, Eq, PartialEq, PartialOrd)]
 pub struct Location {
     line: u64,
@@ -45,7 +46,7 @@ impl Default for Location {
     }
 }
 
-/// A structure for holding the span of comments found
+/// Represents a start/end span (inclusive/exclusive as used by this crate) for a comment in a file.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Span {
     start: Location,

src/comments.rs

@@ -1,5 +1,5 @@
-//! Module for parsing sql and comments and returning `table` and `column`
-//! information, including comments
+//! Convert parsed SQL + extracted comments into structured documentation types.
+
 use core::fmt;
 use std::path::PathBuf;
 
@@ -124,6 +124,12 @@ impl TableDoc {
     pub fn columns_mut(&mut self) -> &mut [ColumnDoc] {
         &mut self.columns
     }
+
+    /// Getter method for retrieving the table's [`PathBuf`]
+    #[must_use]
+    pub const fn path(&self) -> &Option<PathBuf> {
+        &self.path
+    }
 }
 
 impl fmt::Display for TableDoc {
@@ -237,6 +243,7 @@ impl SqlFileDoc {
     }
 }
 
+/// Converts a file doc into its table docs (consumes the [`SqlFileDoc`]).
 impl From<SqlFileDoc> for Vec<TableDoc> {
     fn from(value: SqlFileDoc) -> Self {
         value.tables
@@ -286,7 +293,7 @@ fn schema_and_table(name: &ObjectName) -> Result<(Option<String>, String), DocEr
 #[cfg(test)]
 mod tests {
     use core::fmt;
-    use std::{env, fs};
+    use std::{env, fs, path::PathBuf};
 
     use sqlparser::{
         ast::{Ident, ObjectName, ObjectNamePart, ObjectNamePartFunction},
@@ -849,4 +856,15 @@ CREATE TABLE posts (
         let expected = vec![t1, t2];
         assert_eq!(got, expected);
     }
+    #[test]
+    fn table_doc_path_getter_returns_expected_value() {
+        let mut table = TableDoc::new(None, "users".to_string(), None, Vec::new(), None);
+        assert_eq!(table.path(), &None);
+        let pb = PathBuf::from("some/dir/file.sql");
+        table.set_path(Some(pb.clone()));
+        assert_eq!(table.path(), &Some(pb));
+        let no_path: Option<PathBuf> = None;
+        table.set_path(no_path);
+        assert_eq!(table.path(), &None);
+    }
 }

src/docs.rs

@@ -1,9 +1,12 @@
-//! Module for managing Document Errors as [`DocError`]
+//! Error types returned by this crate’s public APIs.
+
 use crate::{comments::CommentError, docs::TableDoc};
 use core::fmt;
 use sqlparser::parser::ParserError;
 use std::{error, fmt::Debug};
-/// Error enum for returning relevant error based on error type
+
+/// Errors that can occur while discovering, parsing, or documenting SQL files.
+#[non_exhaustive]
 #[derive(Debug)]
 pub enum DocError {
     /// Wrapper for standard [`std::io::Error`]

src/error.rs

@@ -1,5 +1,6 @@
-//! Module that offers utilities for discovering, filtering, and loading `.sql`
-//! files from the filesystem.
+//! Discover and filter `.sql` files on disk.
+//!
+//! This module finds file paths; it does not parse SQL or extract comments.
 
 use std::{
     fs, io,
@@ -37,9 +38,8 @@ impl SqlFilesList {
     /// Creates a list of `.sql` files under `path`, optionally excluding files
     /// whose full paths appear in `deny_list`.
     ///
-    /// Paths in `deny_list` must match exactly the `PathBuf` returned by
-    /// recursion. For convenience, the top-level API accepts `&[&str]`
-    /// instead.
+    /// Deny entries must match the discovered full path exactly (string equality on
+    /// the resulting [`PathBuf`]).
     ///
     /// # Parameters
     ///
@@ -60,7 +60,7 @@ impl SqlFilesList {
         Ok(Self { sql_files: allow_list })
     }
 
-    /// Returns the discovered `.sql` files in their original order.
+    /// Returns discovered `.sql` files in discovery order (filesystem-dependent).
     #[must_use]
     pub fn sql_files(&self) -> &[PathBuf] {
         &self.sql_files

src/files.rs

@@ -1,10 +1,14 @@
 #![doc = include_str!("../README.md")]
-//! Module layout:
-//! - [`files`]    : discover and load `.sql` files from disk
-//! - [`ast`]      : parse SQL into an AST using [`sqlparser`]
-//! - [`comments`] : extract and model comments and spans
-//! - [`docs`]     : Generates a struct to hold [`docs::TableDoc`]
-//! - [`sql_doc`]  : Creates the [`SqlDoc`] structure
+//!
+//! ## Module layout
+//!
+//! - [`files`]    — Discover and load `.sql` files from disk
+//! - [`ast`]      — Parse SQL into an AST using [`sqlparser`]
+//! - [`comments`] — Extract and model SQL comments and spans
+//! - [`docs`]     — Generate structured documentation (`TableDoc`, `ColumnDoc`)
+//! - [`sql_doc`]  — Build the top-level [`SqlDoc`] and primary entry point
+//!
+//! **Start here:** [`SqlDoc::from_dir`] or [`SqlDoc::from_path`]
 
 pub mod ast;
 pub mod comments;

src/lib.rs

@@ -1,4 +1,4 @@
-//! Module for the top level `SqlDoc` structure.
+//! Public entry point for building [`SqlDoc`] from a directory, file, or string.
 
 use std::path::{Path, PathBuf};
 
@@ -10,7 +10,7 @@ use crate::{
     files::{SqlFile, SqlFilesList},
 };
 
-/// Structure for Sql Documentation, built from [`TableDoc`] and
+/// Top-level documentation object containing all discovered [`TableDoc`] entries.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct SqlDoc {
     /// Holds the [`Vec`] of all tables found in all specified files.
@@ -70,7 +70,7 @@ impl SqlDoc {
         }
     }
 
-    /// Method for generating builder from a [`str`]
+    /// Creates a builder from SQL text (no filesystem path is associated) from a [`str`]
     #[must_use]
     pub const fn from_str(content: &str) -> SqlDocBuilder<'_> {
         SqlDocBuilder {
@@ -168,14 +168,17 @@ impl SqlDocBuilder<'_> {
         self.multiline_flat = MultiFlatten::Flatten(suffix.to_string());
         self
     }
-    /// Method to set multiline comments to preserver multiple lines
+    /// Method to set multiline comments to preserve multiple lines
     #[must_use]
     pub fn preserve_multiline(mut self) -> Self {
         self.multiline_flat = MultiFlatten::NoFlat;
         self
     }
     /// Builds the [`SqlDoc`]
     ///
+    ///
+    /// Comment flattening (if enabled) is applied as a post-processing step after docs are generated.
+    ///
     /// # Errors
     /// - Will return `DocError` bubbled up
     pub fn build(self) -> Result<SqlDoc, DocError> {