Clean up tablesample public API and docs.

diesel-rs · Mar 7, 2024 · 8b0ac9b · 8b0ac9b
1 parent 88f8a32
commit 8b0ac9b
Show file tree

Hide file tree

Showing 5 changed files with 19 additions and 13 deletions.
diff --git a/diesel/src/internal/table_macro.rs b/diesel/src/internal/table_macro.rs
@@ -1,6 +1,9 @@
 #[doc(hidden)]
 pub use crate::expression::nullable::Nullable as NullableExpression;
 #[doc(hidden)]
+#[cfg(feature = "postgres_backend")]
+pub use crate::pg::query_builder::tablesample::TablesampleMethod;
+#[doc(hidden)]
 pub use crate::query_builder::from_clause::{FromClause, NoFromClause};
 #[doc(hidden)]
 pub use crate::query_builder::nodes::{

diff --git a/diesel/src/macros/mod.rs b/diesel/src/macros/mod.rs
@@ -246,29 +246,29 @@ macro_rules! __diesel_internal_backend_specific_allow_tables_to_appear_in_same_q
         impl<TSM> $crate::query_source::TableNotEqual<$left::table>
             for $crate::query_builder::Tablesample<$right::table, TSM>
         where
-            TSM: $crate::query_builder::TablesampleMethod,
+            TSM: $crate::internal::table_macro::TablesampleMethod,
         {
         }
         impl<TSM> $crate::query_source::TableNotEqual<$right::table>
             for $crate::query_builder::Tablesample<$left::table, TSM>
         where
-            TSM: $crate::query_builder::TablesampleMethod,
+            TSM: $crate::internal::table_macro::TablesampleMethod,
         {
         }
         impl<TSM>
             $crate::query_source::TableNotEqual<
                 $crate::query_builder::Tablesample<$left::table, TSM>,
             > for $right::table
         where
-            TSM: $crate::query_builder::TablesampleMethod,
+            TSM: $crate::internal::table_macro::TablesampleMethod,
         {
         }
         impl<TSM>
             $crate::query_source::TableNotEqual<
                 $crate::query_builder::Tablesample<$right::table, TSM>,
             > for $left::table
         where
-            TSM: $crate::query_builder::TablesampleMethod,
+            TSM: $crate::internal::table_macro::TablesampleMethod,
         {
         }
     };

diff --git a/diesel/src/pg/expression/extensions/tablesample_dsl.rs b/diesel/src/pg/expression/extensions/tablesample_dsl.rs
@@ -19,7 +19,8 @@ use crate::Table;
 /// a `TABLESAMPLE method(p)` clause where p is specified by the portion argument. The provided
 /// percentage should be an integer between 0 and 100.
 ///
-/// If the seed argument is is Some(f) then f becomes the seed in `TABLESAMPLE ... REPEATABLE (f)`.
+/// To generate a `TABLESAMPLE ... REPEATABLE (f)` clause, you'll need to call
+/// [`.with_seed(f)`](Tablesample::with_seed).
 ///
 /// Example:
 ///

diff --git a/diesel/src/pg/query_builder/tablesample.rs b/diesel/src/pg/query_builder/tablesample.rs
@@ -33,13 +33,12 @@ impl TablesampleMethod for SystemMethod {
 }
 
 /// Represents a query with a `TABLESAMPLE` clause.
-#[doc(hidden)]
 #[derive(Debug, Clone, Copy)]
 pub struct Tablesample<S, TSM>
 where
     TSM: TablesampleMethod,
 {
-    pub source: S,
+    source: S,
     method: PhantomData<TSM>,
     portion: i16,
     seed: Option<f64>,
@@ -49,7 +48,7 @@ impl<S, TSM> Tablesample<S, TSM>
 where
     TSM: TablesampleMethod,
 {
-    pub fn new(source: S, portion: i16) -> Tablesample<S, TSM> {
+    pub(crate) fn new(source: S, portion: i16) -> Tablesample<S, TSM> {
         Tablesample {
             source,
             method: PhantomData,
@@ -58,6 +57,8 @@ where
         }
     }
 
+    /// This method allows you to specify the random number generator seed to use in the sampling
+    /// method. This allows you to obtain repeatable results.
     pub fn with_seed(self, seed: f64) -> Tablesample<S, TSM> {
         Tablesample {
             source: self.source,

diff --git a/diesel_derives/src/table.rs b/diesel_derives/src/table.rs
@@ -176,7 +176,7 @@ pub(crate) fn expand(input: TableDecl) -> TokenStream {
             impl<S, TSM> diesel::JoinTo<diesel::query_builder::Tablesample<S, TSM>> for table
             where
                 diesel::query_builder::Tablesample<S, TSM>: diesel::JoinTo<table>,
-                TSM: diesel::query_builder::TablesampleMethod
+                TSM: diesel::internal::table_macro::TablesampleMethod
             {
                 type FromClause = diesel::query_builder::Tablesample<S, TSM>;
                 type OnClause = <diesel::query_builder::Tablesample<S, TSM> as diesel::JoinTo<table>>::OnClause;
@@ -190,15 +190,15 @@ pub(crate) fn expand(input: TableDecl) -> TokenStream {
             impl<TSM> diesel::query_source::AppearsInFromClause<diesel::query_builder::Tablesample<table, TSM>>
                 for table
                     where
-                TSM:  diesel::query_builder::TablesampleMethod
+                TSM: diesel::internal::table_macro::TablesampleMethod
             {
                 type Count = diesel::query_source::Once;
             }
 
             impl<TSM> diesel::query_source::AppearsInFromClause<table>
                 for diesel::query_builder::Tablesample<table, TSM>
                     where
-                TSM:  diesel::query_builder::TablesampleMethod
+                TSM: diesel::internal::table_macro::TablesampleMethod
             {
                 type Count = diesel::query_source::Once;
             }
@@ -700,12 +700,13 @@ fn expand_column_def(column_def: &ColumnDef) -> TokenStream {
 
             impl<TSM> diesel::query_source::AppearsInFromClause<diesel::query_builder::Tablesample<super::table, TSM>>
                 for #column_name
-                where TSM:  diesel::query_builder::TablesampleMethod
+                    where
+                TSM: diesel::internal::table_macro::TablesampleMethod
             {
                 type Count = diesel::query_source::Once;
             }
             impl<TSM> diesel::SelectableExpression<diesel::query_builder::Tablesample<super::table, TSM>>
-                for #column_name where TSM: diesel::query_builder::TablesampleMethod {}
+                for #column_name where TSM: diesel::internal::table_macro::TablesampleMethod {}
         })
     } else {
         None