Merge pull request #1226 from prisma/sql-schema-describer/document-walkers

tomhoule · web-flow · commit 369b3694b7ed · 2020-10-13T10:25:37.000+02:00
Add #[deny(missing_docs)] to sql_schema_describer::walkers and document
diff --git a/libs/sql-schema-describer/src/walkers.rs b/libs/sql-schema-describer/src/walkers.rs
@@ -1,8 +1,13 @@
+//! Functions and types for conveniently traversing and querying a SqlSchema.
+
+#![deny(missing_docs)]
+
 use crate::{
     Column, ColumnArity, ColumnType, ColumnTypeFamily, DefaultValue, Enum, ForeignKey, Index, IndexType, PrimaryKey,
     SqlSchema, Table,
 };
 
+/// Traverse all the columns in the schema.
 pub fn walk_columns<'a>(schema: &'a SqlSchema) -> impl Iterator<Item = ColumnWalker<'a>> + 'a {
     schema.tables.iter().flat_map(move |table| {
         table
@@ -12,6 +17,7 @@ pub fn walk_columns<'a>(schema: &'a SqlSchema) -> impl Iterator<Item = ColumnWal
     })
 }
 
+/// Find a column by table and column name in the schema.
 pub fn find_column<'a>(schema: &'a SqlSchema, table_name: &str, column_name: &str) -> Option<ColumnWalker<'a>> {
     schema
         .tables
@@ -26,22 +32,29 @@ pub fn find_column<'a>(schema: &'a SqlSchema, table_name: &str, column_name: &st
         })
 }
 
+/// Traverse a table column.
 #[derive(Debug, Clone, Copy)]
 pub struct ColumnWalker<'a> {
+    /// The schema the column is contained in. This field will become private.
     pub schema: &'a SqlSchema,
+    /// The underlying column struct. This field will become private.
     pub column: &'a Column,
+    /// The underlying table struct. This field will become private.
     pub table: &'a Table,
 }
 
 impl<'a> ColumnWalker<'a> {
+    /// The nullability and arity of the column.
     pub fn arity(&self) -> &ColumnArity {
         &self.column.tpe.arity
     }
 
+    /// The type family.
     pub fn column_type_family(&self) -> &'a ColumnTypeFamily {
         &self.column.tpe.family
     }
 
+    /// Extract an `Enum` column type family, or `None` if the family is something else.
     pub fn column_type_family_as_enum(&self) -> Option<&'a Enum> {
         self.column_type_family().as_enum().map(|enum_name| {
             self.schema()
@@ -51,22 +64,27 @@ impl<'a> ColumnWalker<'a> {
         })
     }
 
+    /// The column name.
     pub fn name(&self) -> &'a str {
         &self.column.name
     }
 
+    /// The default value for the column.
     pub fn default(&self) -> Option<&'a DefaultValue> {
         self.column.default.as_ref()
     }
 
+    /// The full column type.
     pub fn column_type(&self) -> &'a ColumnType {
         &self.column.tpe
     }
 
+    /// Is this column an auto-incrementing integer?
     pub fn is_autoincrement(&self) -> bool {
         self.column.auto_increment
     }
 
+    /// Returns whether two columns are named the same and belong to the same table.
     pub fn is_same_column(&self, other: &ColumnWalker<'_>) -> bool {
         self.name() == other.name() && self.table().name() == other.table().name()
     }
@@ -79,33 +97,41 @@ impl<'a> ColumnWalker<'a> {
             .unwrap_or(false)
     }
 
+    /// Traverse to the column's table.
     pub fn table(&self) -> TableWalker<'a> {
         TableWalker {
             schema: self.schema,
             table: self.table,
         }
     }
 
+    /// Get a reference to the SQL schema the column is part of.
     pub fn schema(&self) -> &'a SqlSchema {
         self.schema
     }
 }
 
+/// Traverse a table.
 #[derive(Clone, Copy)]
 pub struct TableWalker<'a> {
+    /// The schema the column is contained in. This field will become private.
     pub schema: &'a SqlSchema,
+    /// The underlying table struct. This field will become private.
     pub table: &'a Table,
 }
 
 impl<'a> TableWalker<'a> {
+    /// Create a TableWalker from a schema and a reference to one of its tables.
     pub fn new(schema: &'a SqlSchema, table: &'a Table) -> Self {
         Self { schema, table }
     }
 
+    /// Get a column in the table, by name.
     pub fn column(&self, column_name: &str) -> Option<ColumnWalker<'a>> {
         self.columns().find(|column| column.name() == column_name)
     }
 
+    /// Traverse the table's columns.
     pub fn columns<'b>(&'b self) -> impl Iterator<Item = ColumnWalker<'a>> + 'b {
         self.table.columns.iter().map(move |column| ColumnWalker {
             column,
@@ -114,6 +140,7 @@ impl<'a> TableWalker<'a> {
         })
     }
 
+    /// Traverse the indexes on the table.
     pub fn indexes<'b>(&'b self) -> impl Iterator<Item = IndexWalker<'a>> + 'b {
         self.table.indices.iter().map(move |index| IndexWalker {
             index,
@@ -122,54 +149,65 @@ impl<'a> TableWalker<'a> {
         })
     }
 
+    /// Traverse the foreign keys on the table.
     pub fn foreign_keys(self) -> impl Iterator<Item = ForeignKeyWalker<'a>> {
         self.table.foreign_keys.iter().map(move |foreign_key| ForeignKeyWalker {
             foreign_key,
             table: self,
         })
     }
 
+    /// The table name.
     pub fn name(&self) -> &'a str {
         &self.table.name
     }
 
+    /// Try to traverse a foreign key for a single column.
     pub fn foreign_key_for_column(&self, column: &str) -> Option<&'a ForeignKey> {
         self.table.foreign_key_for_column(column)
     }
 
+    /// Traverse to the primary key of the table.
     pub fn primary_key(&self) -> Option<&'a PrimaryKey> {
         self.table.primary_key.as_ref()
     }
 }
 
+/// Traverse a foreign key.
 pub struct ForeignKeyWalker<'schema> {
     table: TableWalker<'schema>,
     foreign_key: &'schema ForeignKey,
 }
 
 impl<'a, 'schema> ForeignKeyWalker<'schema> {
+    /// The names of the foreign key columns on the referencing table.
     pub fn constrained_column_names(&self) -> &[String] {
         &self.foreign_key.columns
     }
 
+    /// The foreign key columns on the referencing table.
     pub fn constrained_columns<'b>(&'b self) -> impl Iterator<Item = ColumnWalker<'schema>> + 'b {
         self.table()
             .columns()
             .filter(move |column| self.foreign_key.columns.contains(&column.column.name))
     }
 
+    /// The name of the foreign key constraint.
     pub fn constraint_name(&self) -> Option<&'schema str> {
         self.foreign_key.constraint_name.as_deref()
     }
 
+    /// Access the underlying ForeignKey struct.
     pub fn inner(&self) -> &'schema ForeignKey {
         self.foreign_key
     }
 
+    /// The number of columns referenced by the constraint.
     pub fn referenced_columns_count(&self) -> usize {
         self.foreign_key.referenced_columns.len()
     }
 
+    /// The table the foreign key "points to".
     pub fn referenced_table(&self) -> TableWalker<'schema> {
         TableWalker {
             schema: self.table.schema,
@@ -181,22 +219,26 @@ impl<'a, 'schema> ForeignKeyWalker<'schema> {
         }
     }
 
+    /// Traverse to the referencing table.
     pub fn table(&self) -> &TableWalker<'schema> {
         &self.table
     }
 }
 
+/// Traverse an index.
 pub struct IndexWalker<'a> {
     schema: &'a SqlSchema,
     table: &'a Table,
     index: &'a Index,
 }
 
 impl<'a> IndexWalker<'a> {
+    /// The names of the indexed columns.
     pub fn column_names(&self) -> &[String] {
         &self.index.columns
     }
 
+    /// Traverse the indexed columns.
     pub fn columns<'b>(&'b self) -> impl Iterator<Item = ColumnWalker<'a>> + 'b {
         self.index
             .columns
@@ -215,24 +257,30 @@ impl<'a> IndexWalker<'a> {
             })
     }
 
+    /// Is any of the indexed columns nullable?
     pub fn has_nullable_columns(&self) -> bool {
         self.columns().any(|c| c.arity().is_nullable())
     }
 
+    /// The underlying index struct.
     pub fn index(&self) -> &Index {
         &self.index
     }
 
+    /// The IndexType
     pub fn index_type(&self) -> &IndexType {
         &self.index.tpe
     }
 
+    /// The name of the index.
     pub fn name(&self) -> &str {
         &self.index.name
     }
 }
 
+/// Extension methods for the traversal of a SqlSchema.
 pub trait SqlSchemaExt {
+    /// Find a table by name.
     fn table_walker<'a>(&'a self, name: &str) -> Option<TableWalker<'a>>;
 }
 

Original file line number	Diff line number	Diff line change
`@@ -1,8 +1,13 @@`
	`1`	`+//! Functions and types for conveniently traversing and querying a SqlSchema.`
	`2`	`+`
	`3`	`+#![deny(missing_docs)]`
	`4`	`+`
`1`	`5`	`use crate::{`
`2`	`6`	`Column, ColumnArity, ColumnType, ColumnTypeFamily, DefaultValue, Enum, ForeignKey, Index, IndexType, PrimaryKey,`
`3`	`7`	`SqlSchema, Table,`
`4`	`8`	`};`
`5`	`9`
	`10`	`+/// Traverse all the columns in the schema.`
`6`	`11`	`pub fn walk_columns<'a>(schema: &'a SqlSchema) -> impl Iterator<Item = ColumnWalker<'a>> + 'a {`
`7`	`12`	`schema.tables.iter().flat_map(move \|table\| {`
`8`	`13`	`table`
`@@ -12,6 +17,7 @@ pub fn walk_columns<'a>(schema: &'a SqlSchema) -> impl Iterator<Item = ColumnWal`
`12`	`17`	`})`
`13`	`18`	`}`
`14`	`19`
	`20`	`+/// Find a column by table and column name in the schema.`
`15`	`21`	`pub fn find_column<'a>(schema: &'a SqlSchema, table_name: &str, column_name: &str) -> Option<ColumnWalker<'a>> {`
`16`	`22`	`schema`
`17`	`23`	`.tables`
`@@ -26,22 +32,29 @@ pub fn find_column<'a>(schema: &'a SqlSchema, table_name: &str, column_name: &st`
`26`	`32`	`})`
`27`	`33`	`}`
`28`	`34`
	`35`	`+/// Traverse a table column.`
`29`	`36`	`#[derive(Debug, Clone, Copy)]`
`30`	`37`	`pub struct ColumnWalker<'a> {`
	`38`	`+ /// The schema the column is contained in. This field will become private.`
`31`	`39`	`pub schema: &'a SqlSchema,`
	`40`	`+ /// The underlying column struct. This field will become private.`
`32`	`41`	`pub column: &'a Column,`
	`42`	`+ /// The underlying table struct. This field will become private.`
`33`	`43`	`pub table: &'a Table,`
`34`	`44`	`}`
`35`	`45`
`36`	`46`	`impl<'a> ColumnWalker<'a> {`
	`47`	`+ /// The nullability and arity of the column.`
`37`	`48`	`pub fn arity(&self) -> &ColumnArity {`
`38`	`49`	`&self.column.tpe.arity`
`39`	`50`	`}`
`40`	`51`
	`52`	`+ /// The type family.`
`41`	`53`	`pub fn column_type_family(&self) -> &'a ColumnTypeFamily {`
`42`	`54`	`&self.column.tpe.family`
`43`	`55`	`}`
`44`	`56`
	`57`	+ /// Extract an `Enum` column type family, or `None` if the family is something else.
`45`	`58`	`pub fn column_type_family_as_enum(&self) -> Option<&'a Enum> {`
`46`	`59`	`self.column_type_family().as_enum().map(\|enum_name\| {`
`47`	`60`	`self.schema()`
`@@ -51,22 +64,27 @@ impl<'a> ColumnWalker<'a> {`
`51`	`64`	`})`
`52`	`65`	`}`
`53`	`66`
	`67`	`+ /// The column name.`
`54`	`68`	`pub fn name(&self) -> &'a str {`
`55`	`69`	`&self.column.name`
`56`	`70`	`}`
`57`	`71`
	`72`	`+ /// The default value for the column.`
`58`	`73`	`pub fn default(&self) -> Option<&'a DefaultValue> {`
`59`	`74`	`self.column.default.as_ref()`
`60`	`75`	`}`
`61`	`76`
	`77`	`+ /// The full column type.`
`62`	`78`	`pub fn column_type(&self) -> &'a ColumnType {`
`63`	`79`	`&self.column.tpe`
`64`	`80`	`}`
`65`	`81`
	`82`	`+ /// Is this column an auto-incrementing integer?`
`66`	`83`	`pub fn is_autoincrement(&self) -> bool {`
`67`	`84`	`self.column.auto_increment`
`68`	`85`	`}`
`69`	`86`
	`87`	`+ /// Returns whether two columns are named the same and belong to the same table.`
`70`	`88`	`pub fn is_same_column(&self, other: &ColumnWalker<'_>) -> bool {`
`71`	`89`	`self.name() == other.name() && self.table().name() == other.table().name()`
`72`	`90`	`}`
`@@ -79,33 +97,41 @@ impl<'a> ColumnWalker<'a> {`
`79`	`97`	`.unwrap_or(false)`
`80`	`98`	`}`
`81`	`99`
	`100`	`+ /// Traverse to the column's table.`
`82`	`101`	`pub fn table(&self) -> TableWalker<'a> {`
`83`	`102`	`TableWalker {`
`84`	`103`	`schema: self.schema,`
`85`	`104`	`table: self.table,`
`86`	`105`	`}`
`87`	`106`	`}`
`88`	`107`
	`108`	`+ /// Get a reference to the SQL schema the column is part of.`
`89`	`109`	`pub fn schema(&self) -> &'a SqlSchema {`
`90`	`110`	`self.schema`
`91`	`111`	`}`
`92`	`112`	`}`
`93`	`113`
	`114`	`+/// Traverse a table.`
`94`	`115`	`#[derive(Clone, Copy)]`
`95`	`116`	`pub struct TableWalker<'a> {`
	`117`	`+ /// The schema the column is contained in. This field will become private.`
`96`	`118`	`pub schema: &'a SqlSchema,`
	`119`	`+ /// The underlying table struct. This field will become private.`
`97`	`120`	`pub table: &'a Table,`
`98`	`121`	`}`
`99`	`122`
`100`	`123`	`impl<'a> TableWalker<'a> {`
	`124`	`+ /// Create a TableWalker from a schema and a reference to one of its tables.`
`101`	`125`	`pub fn new(schema: &'a SqlSchema, table: &'a Table) -> Self {`
`102`	`126`	`Self { schema, table }`
`103`	`127`	`}`
`104`	`128`
	`129`	`+ /// Get a column in the table, by name.`
`105`	`130`	`pub fn column(&self, column_name: &str) -> Option<ColumnWalker<'a>> {`
`106`	`131`	`self.columns().find(\|column\| column.name() == column_name)`
`107`	`132`	`}`
`108`	`133`
	`134`	`+ /// Traverse the table's columns.`
`109`	`135`	`pub fn columns<'b>(&'b self) -> impl Iterator<Item = ColumnWalker<'a>> + 'b {`
`110`	`136`	`self.table.columns.iter().map(move \|column\| ColumnWalker {`
`111`	`137`	`column,`
`@@ -114,6 +140,7 @@ impl<'a> TableWalker<'a> {`
`114`	`140`	`})`
`115`	`141`	`}`
`116`	`142`
	`143`	`+ /// Traverse the indexes on the table.`
`117`	`144`	`pub fn indexes<'b>(&'b self) -> impl Iterator<Item = IndexWalker<'a>> + 'b {`
`118`	`145`	`self.table.indices.iter().map(move \|index\| IndexWalker {`
`119`	`146`	`index,`
`@@ -122,54 +149,65 @@ impl<'a> TableWalker<'a> {`
`122`	`149`	`})`
`123`	`150`	`}`
`124`	`151`
	`152`	`+ /// Traverse the foreign keys on the table.`
`125`	`153`	`pub fn foreign_keys(self) -> impl Iterator<Item = ForeignKeyWalker<'a>> {`
`126`	`154`	`self.table.foreign_keys.iter().map(move \|foreign_key\| ForeignKeyWalker {`
`127`	`155`	`foreign_key,`
`128`	`156`	`table: self,`
`129`	`157`	`})`
`130`	`158`	`}`
`131`	`159`
	`160`	`+ /// The table name.`
`132`	`161`	`pub fn name(&self) -> &'a str {`
`133`	`162`	`&self.table.name`
`134`	`163`	`}`
`135`	`164`
	`165`	`+ /// Try to traverse a foreign key for a single column.`
`136`	`166`	`pub fn foreign_key_for_column(&self, column: &str) -> Option<&'a ForeignKey> {`
`137`	`167`	`self.table.foreign_key_for_column(column)`
`138`	`168`	`}`
`139`	`169`
	`170`	`+ /// Traverse to the primary key of the table.`
`140`	`171`	`pub fn primary_key(&self) -> Option<&'a PrimaryKey> {`
`141`	`172`	`self.table.primary_key.as_ref()`
`142`	`173`	`}`
`143`	`174`	`}`
`144`	`175`
	`176`	`+/// Traverse a foreign key.`
`145`	`177`	`pub struct ForeignKeyWalker<'schema> {`
`146`	`178`	`table: TableWalker<'schema>,`
`147`	`179`	`foreign_key: &'schema ForeignKey,`
`148`	`180`	`}`
`149`	`181`
`150`	`182`	`impl<'a, 'schema> ForeignKeyWalker<'schema> {`
	`183`	`+ /// The names of the foreign key columns on the referencing table.`
`151`	`184`	`pub fn constrained_column_names(&self) -> &[String] {`
`152`	`185`	`&self.foreign_key.columns`
`153`	`186`	`}`
`154`	`187`
	`188`	`+ /// The foreign key columns on the referencing table.`
`155`	`189`	`pub fn constrained_columns<'b>(&'b self) -> impl Iterator<Item = ColumnWalker<'schema>> + 'b {`
`156`	`190`	`self.table()`
`157`	`191`	`.columns()`
`158`	`192`	`.filter(move \|column\| self.foreign_key.columns.contains(&column.column.name))`
`159`	`193`	`}`
`160`	`194`
	`195`	`+ /// The name of the foreign key constraint.`
`161`	`196`	`pub fn constraint_name(&self) -> Option<&'schema str> {`
`162`	`197`	`self.foreign_key.constraint_name.as_deref()`
`163`	`198`	`}`
`164`	`199`
	`200`	`+ /// Access the underlying ForeignKey struct.`
`165`	`201`	`pub fn inner(&self) -> &'schema ForeignKey {`
`166`	`202`	`self.foreign_key`
`167`	`203`	`}`
`168`	`204`
	`205`	`+ /// The number of columns referenced by the constraint.`
`169`	`206`	`pub fn referenced_columns_count(&self) -> usize {`
`170`	`207`	`self.foreign_key.referenced_columns.len()`
`171`	`208`	`}`
`172`	`209`
	`210`	`+ /// The table the foreign key "points to".`
`173`	`211`	`pub fn referenced_table(&self) -> TableWalker<'schema> {`
`174`	`212`	`TableWalker {`
`175`	`213`	`schema: self.table.schema,`
`@@ -181,22 +219,26 @@ impl<'a, 'schema> ForeignKeyWalker<'schema> {`
`181`	`219`	`}`
`182`	`220`	`}`
`183`	`221`
	`222`	`+ /// Traverse to the referencing table.`
`184`	`223`	`pub fn table(&self) -> &TableWalker<'schema> {`
`185`	`224`	`&self.table`
`186`	`225`	`}`
`187`	`226`	`}`
`188`	`227`
	`228`	`+/// Traverse an index.`
`189`	`229`	`pub struct IndexWalker<'a> {`
`190`	`230`	`schema: &'a SqlSchema,`
`191`	`231`	`table: &'a Table,`
`192`	`232`	`index: &'a Index,`
`193`	`233`	`}`
`194`	`234`
`195`	`235`	`impl<'a> IndexWalker<'a> {`
	`236`	`+ /// The names of the indexed columns.`
`196`	`237`	`pub fn column_names(&self) -> &[String] {`
`197`	`238`	`&self.index.columns`
`198`	`239`	`}`
`199`	`240`
	`241`	`+ /// Traverse the indexed columns.`
`200`	`242`	`pub fn columns<'b>(&'b self) -> impl Iterator<Item = ColumnWalker<'a>> + 'b {`
`201`	`243`	`self.index`
`202`	`244`	`.columns`
`@@ -215,24 +257,30 @@ impl<'a> IndexWalker<'a> {`
`215`	`257`	`})`
`216`	`258`	`}`
`217`	`259`
	`260`	`+ /// Is any of the indexed columns nullable?`
`218`	`261`	`pub fn has_nullable_columns(&self) -> bool {`
`219`	`262`	`self.columns().any(\|c\| c.arity().is_nullable())`
`220`	`263`	`}`
`221`	`264`
	`265`	`+ /// The underlying index struct.`
`222`	`266`	`pub fn index(&self) -> &Index {`
`223`	`267`	`&self.index`
`224`	`268`	`}`
`225`	`269`
	`270`	`+ /// The IndexType`
`226`	`271`	`pub fn index_type(&self) -> &IndexType {`
`227`	`272`	`&self.index.tpe`
`228`	`273`	`}`
`229`	`274`
	`275`	`+ /// The name of the index.`
`230`	`276`	`pub fn name(&self) -> &str {`
`231`	`277`	`&self.index.name`
`232`	`278`	`}`
`233`	`279`	`}`
`234`	`280`
	`281`	`+/// Extension methods for the traversal of a SqlSchema.`
`235`	`282`	`pub trait SqlSchemaExt {`
	`283`	`+ /// Find a table by name.`
`236`	`284`	`fn table_walker<'a>(&'a self, name: &str) -> Option<TableWalker<'a>>;`
`237`	`285`	`}`
`238`	`286`