feat(code): add doccomments to generated functions

src/code.rs

@@ -454,6 +454,7 @@ fn build_table_fns(
         if create_struct.has_fields() {
             buffer.push_str(&format!(
             r##"
+    /// Insert a new row into `{table_name}` with a given [`{create_struct_identifier}`]
     pub{async_keyword} fn create(db: &mut ConnectionType, item: &{create_struct_identifier}) -> QueryResult<Self> {{
         use {schema_path}{table_name}::dsl::*;
 
@@ -464,6 +465,7 @@ fn build_table_fns(
         } else {
             buffer.push_str(&format!(
                 r##"
+    /// Insert a new row into `{table_name}` with all default values
     pub{async_keyword} fn create(db: &mut ConnectionType) -> QueryResult<Self> {{
         use {schema_path}{table_name}::dsl::*;
 
@@ -474,8 +476,16 @@ fn build_table_fns(
         }
     }
 
+    // this will also trigger for 0 primary keys, but diesel currently does not support that
+    let key_maybe_multiple = if primary_column_name_and_type.len() <= 1 {
+        "key"
+    } else {
+        "keys"
+    };
+
     buffer.push_str(&format!(
         r##"
+    /// Get a row from `{table_name}`, identified by the primary {key_maybe_multiple}
     pub{async_keyword} fn read(db: &mut ConnectionType, {item_id_params}) -> QueryResult<Self> {{
         use {schema_path}{table_name}::dsl::*;
 
@@ -514,6 +524,7 @@ fn build_table_fns(
         // we should generate an update() method.
 
         buffer.push_str(&format!(r##"
+    /// Update a row in `{table_name}`, identified by the primary {key_maybe_multiple} with [`{update_struct_identifier}`]
     pub{async_keyword} fn update(db: &mut ConnectionType, {item_id_params}, item: &{update_struct_identifier}) -> QueryResult<Self> {{
         use {schema_path}{table_name}::dsl::*;
 
@@ -525,6 +536,7 @@ fn build_table_fns(
     if !is_readonly {
         buffer.push_str(&format!(
             r##"
+    /// Delete a row in `{table_name}`, identified by the primary {key_maybe_multiple}
     pub{async_keyword} fn delete(db: &mut ConnectionType, {item_id_params}) -> QueryResult<usize> {{
         use {schema_path}{table_name}::dsl::*;
 

test/autogenerated_all/models/todos/generated.rs

@@ -36,12 +36,14 @@ pub struct PaginationResult<T> {
 }
 
 impl Todos {
+    /// Insert a new row into `todos` with all default values
     pub fn create(db: &mut ConnectionType) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         insert_into(todos).default_values().get_result::<Self>(db)
     }
 
+    /// Get a row from `todos`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param_id: i32) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
@@ -66,12 +68,14 @@ impl Todos {
         })
     }
 
+    /// Update a row in `todos`, identified by the primary key with [`UpdateTodos`]
     pub fn update(db: &mut ConnectionType, param_id: i32, item: &UpdateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         diesel::update(todos.filter(id.eq(param_id))).set(item).get_result(db)
     }
 
+    /// Delete a row in `todos`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param_id: i32) -> QueryResult<usize> {
         use crate::schema::todos::dsl::*;
 

test/autogenerated_attributes/models/todos/generated.rs

@@ -44,12 +44,14 @@ pub struct PaginationResult<T> {
 }
 
 impl Todos {
+    /// Insert a new row into `todos` with a given [`CreateTodos`]
     pub fn create(db: &mut ConnectionType, item: &CreateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         insert_into(todos).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `todos`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param_id: i32) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
@@ -74,12 +76,14 @@ impl Todos {
         })
     }
 
+    /// Update a row in `todos`, identified by the primary key with [`UpdateTodos`]
     pub fn update(db: &mut ConnectionType, param_id: i32, item: &UpdateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         diesel::update(todos.filter(id.eq(param_id))).set(item).get_result(db)
     }
 
+    /// Delete a row in `todos`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param_id: i32) -> QueryResult<usize> {
         use crate::schema::todos::dsl::*;
 

test/autogenerated_primary_keys/models/todos/generated.rs

@@ -44,12 +44,14 @@ pub struct PaginationResult<T> {
 }
 
 impl Todos {
+    /// Insert a new row into `todos` with a given [`CreateTodos`]
     pub fn create(db: &mut ConnectionType, item: &CreateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         insert_into(todos).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `todos`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param_id: i32) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
@@ -74,12 +76,14 @@ impl Todos {
         })
     }
 
+    /// Update a row in `todos`, identified by the primary key with [`UpdateTodos`]
     pub fn update(db: &mut ConnectionType, param_id: i32, item: &UpdateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         diesel::update(todos.filter(id.eq(param_id))).set(item).get_result(db)
     }
 
+    /// Delete a row in `todos`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param_id: i32) -> QueryResult<usize> {
         use crate::schema::todos::dsl::*;
 

test/cleanup_generated_content/models/todos/generated.rs

@@ -60,12 +60,14 @@ pub struct PaginationResult<T> {
 }
 
 impl Todos {
+    /// Insert a new row into `todos` with a given [`CreateTodos`]
     pub fn create(db: &mut ConnectionType, item: &CreateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         insert_into(todos).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `todos`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param_id: i32) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
@@ -90,12 +92,14 @@ impl Todos {
         })
     }
 
+    /// Update a row in `todos`, identified by the primary key with [`UpdateTodos`]
     pub fn update(db: &mut ConnectionType, param_id: i32, item: &UpdateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         diesel::update(todos.filter(id.eq(param_id))).set(item).get_result(db)
     }
 
+    /// Delete a row in `todos`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param_id: i32) -> QueryResult<usize> {
         use crate::schema::todos::dsl::*;
 

test/create_update_str_cow/models/todos/generated.rs

@@ -58,12 +58,14 @@ pub struct PaginationResult<T> {
 }
 
 impl Todos {
+    /// Insert a new row into `todos` with a given [`CreateTodos`]
     pub fn create(db: &mut ConnectionType, item: &CreateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         insert_into(todos).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `todos`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param_text: String) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
@@ -88,12 +90,14 @@ impl Todos {
         })
     }
 
+    /// Update a row in `todos`, identified by the primary key with [`UpdateTodos`]
     pub fn update(db: &mut ConnectionType, param_text: String, item: &UpdateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         diesel::update(todos.filter(text.eq(param_text))).set(item).get_result(db)
     }
 
+    /// Delete a row in `todos`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param_text: String) -> QueryResult<usize> {
         use crate::schema::todos::dsl::*;
 

test/create_update_str_str/models/todos/generated.rs

@@ -58,12 +58,14 @@ pub struct PaginationResult<T> {
 }
 
 impl Todos {
+    /// Insert a new row into `todos` with a given [`CreateTodos`]
     pub fn create(db: &mut ConnectionType, item: &CreateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         insert_into(todos).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `todos`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param_text: String) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
@@ -88,12 +90,14 @@ impl Todos {
         })
     }
 
+    /// Update a row in `todos`, identified by the primary key with [`UpdateTodos`]
     pub fn update(db: &mut ConnectionType, param_text: String, item: &UpdateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         diesel::update(todos.filter(text.eq(param_text))).set(item).get_result(db)
     }
 
+    /// Delete a row in `todos`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param_text: String) -> QueryResult<usize> {
         use crate::schema::todos::dsl::*;
 

test/custom_model_and_schema_path/models/tableA/generated.rs

@@ -34,12 +34,14 @@ pub struct PaginationResult<T> {
 }
 
 impl TableA {
+    /// Insert a new row into `tableA` with a given [`CreateTableA`]
     pub fn create(db: &mut ConnectionType, item: &CreateTableA) -> QueryResult<Self> {
         use crate::data::schema::tableA::dsl::*;
 
         insert_into(tableA).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `tableA`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param__id: i32) -> QueryResult<Self> {
         use crate::data::schema::tableA::dsl::*;
 
@@ -64,6 +66,7 @@ impl TableA {
         })
     }
 
+    /// Delete a row in `tableA`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param__id: i32) -> QueryResult<usize> {
         use crate::data::schema::tableA::dsl::*;
 

test/custom_model_and_schema_path/models/tableB/generated.rs

@@ -47,12 +47,14 @@ pub struct PaginationResult<T> {
 }
 
 impl TableB {
+    /// Insert a new row into `tableB` with a given [`CreateTableB`]
     pub fn create(db: &mut ConnectionType, item: &CreateTableB) -> QueryResult<Self> {
         use crate::data::schema::tableB::dsl::*;
 
         insert_into(tableB).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `tableB`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param__id: i32) -> QueryResult<Self> {
         use crate::data::schema::tableB::dsl::*;
 
@@ -77,12 +79,14 @@ impl TableB {
         })
     }
 
+    /// Update a row in `tableB`, identified by the primary key with [`UpdateTableB`]
     pub fn update(db: &mut ConnectionType, param__id: i32, item: &UpdateTableB) -> QueryResult<Self> {
         use crate::data::schema::tableB::dsl::*;
 
         diesel::update(tableB.filter(_id.eq(param__id))).set(item).get_result(db)
     }
 
+    /// Delete a row in `tableB`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param__id: i32) -> QueryResult<usize> {
         use crate::data::schema::tableB::dsl::*;
 

test/custom_model_path/models/tableA/generated.rs

@@ -34,12 +34,14 @@ pub struct PaginationResult<T> {
 }
 
 impl TableA {
+    /// Insert a new row into `tableA` with a given [`CreateTableA`]
     pub fn create(db: &mut ConnectionType, item: &CreateTableA) -> QueryResult<Self> {
         use crate::schema::tableA::dsl::*;
 
         insert_into(tableA).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `tableA`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param__id: i32) -> QueryResult<Self> {
         use crate::schema::tableA::dsl::*;
 
@@ -64,6 +66,7 @@ impl TableA {
         })
     }
 
+    /// Delete a row in `tableA`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param__id: i32) -> QueryResult<usize> {
         use crate::schema::tableA::dsl::*;
 

test/custom_model_path/models/tableB/generated.rs

@@ -47,12 +47,14 @@ pub struct PaginationResult<T> {
 }
 
 impl TableB {
+    /// Insert a new row into `tableB` with a given [`CreateTableB`]
     pub fn create(db: &mut ConnectionType, item: &CreateTableB) -> QueryResult<Self> {
         use crate::schema::tableB::dsl::*;
 
         insert_into(tableB).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `tableB`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param__id: i32) -> QueryResult<Self> {
         use crate::schema::tableB::dsl::*;
 
@@ -77,12 +79,14 @@ impl TableB {
         })
     }
 
+    /// Update a row in `tableB`, identified by the primary key with [`UpdateTableB`]
     pub fn update(db: &mut ConnectionType, param__id: i32, item: &UpdateTableB) -> QueryResult<Self> {
         use crate::schema::tableB::dsl::*;
 
         diesel::update(tableB.filter(_id.eq(param__id))).set(item).get_result(db)
     }
 
+    /// Delete a row in `tableB`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param__id: i32) -> QueryResult<usize> {
         use crate::schema::tableB::dsl::*;
 

test/manual_primary_keys/models/todos/generated.rs

@@ -34,12 +34,14 @@ pub struct PaginationResult<T> {
 }
 
 impl Todos {
+    /// Insert a new row into `todos` with a given [`CreateTodos`]
     pub fn create(db: &mut ConnectionType, item: &CreateTodos) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
         insert_into(todos).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `todos`, identified by the primary key
     pub fn read(db: &mut ConnectionType, param_id: i32) -> QueryResult<Self> {
         use crate::schema::todos::dsl::*;
 
@@ -64,6 +66,7 @@ impl Todos {
         })
     }
 
+    /// Delete a row in `todos`, identified by the primary key
     pub fn delete(db: &mut ConnectionType, param_id: i32) -> QueryResult<usize> {
         use crate::schema::todos::dsl::*;
 

test/multiple_primary_keys/models/users/generated.rs

@@ -50,12 +50,14 @@ pub struct PaginationResult<T> {
 }
 
 impl Users {
+    /// Insert a new row into `users` with a given [`CreateUsers`]
     pub fn create(db: &mut ConnectionType, item: &CreateUsers) -> QueryResult<Self> {
         use crate::schema::users::dsl::*;
 
         insert_into(users).values(item).get_result::<Self>(db)
     }
 
+    /// Get a row from `users`, identified by the primary keys
     pub fn read(db: &mut ConnectionType, param_name: String, param_address: String) -> QueryResult<Self> {
         use crate::schema::users::dsl::*;
 
@@ -80,12 +82,14 @@ impl Users {
         })
     }
 
+    /// Update a row in `users`, identified by the primary keys with [`UpdateUsers`]
     pub fn update(db: &mut ConnectionType, param_name: String, param_address: String, item: &UpdateUsers) -> QueryResult<Self> {
         use crate::schema::users::dsl::*;
 
         diesel::update(users.filter(name.eq(param_name)).filter(address.eq(param_address))).set(item).get_result(db)
     }
 
+    /// Delete a row in `users`, identified by the primary keys
     pub fn delete(db: &mut ConnectionType, param_name: String, param_address: String) -> QueryResult<usize> {
         use crate::schema::users::dsl::*;