clarify docstrings, put down TODOs based on review feedback

1 files changed, 6 insertions, 1 deletions

diff --git a/query.go b/query.go
index 0296c13..de151a6 100644
--- a/query.go
+++ b/query.go
@@ -38,6 +38,7 @@ func prepare(ctx context.Context, db Handle, query, operation string, inputSize
 //
 // Fields that are declared with the "auto" tag will not be written into the DB,
 // and instead their value (as auto-generated by the DB on insert) will be placed in the record.
+// (This is why this method, as well as [Store.Upsert], need to take their arguments by-pointer instead of by-value).
 //
 // Returns an error if [NewStore] was called without the [TableNameIs] option, which is required to generate a query for this method.
 //
@@ -77,6 +78,7 @@ func (s Store[R]) insertUsing(ctx context.Context, stmt handle.Statement, db Han
 }
 
 func insertRecord(ctx context.Context, v reflect.Value, recordIndex int, stmt handle.Statement, argumentIndexes [][]int, argumentSlots []any, scanIndexes [][]int, scanSlots []any) error {
+	// TODO: check plan.IndexesOfTransparentPointerStructs, return error (instead of panicking on FieldByIndex) if pointer struct is nil
 	for idx, index := range argumentIndexes {
 		argumentSlots[idx] = v.FieldByIndex(index).Interface()
 	}
@@ -132,6 +134,7 @@ func (s Store[R]) Update(ctx context.Context, db Handle, records ...R) error {
 }
 
 func updateRecord(ctx context.Context, v reflect.Value, recordIndex int, stmt handle.Statement, argumentIndexes [][]int, argumentSlots []any) (int64, error) {
+	// TODO: check plan.IndexesOfTransparentPointerStructs, return error (instead of panicking on FieldByIndex) if pointer struct is nil
 	for idx, index := range argumentIndexes {
 		argumentSlots[idx] = v.FieldByIndex(index).Interface()
 	}
@@ -175,6 +178,8 @@ func (s Store[R]) Delete(ctx context.Context, db Handle, records ...R) error {
 }
 
 func deleteRecord(ctx context.Context, v reflect.Value, recordIndex int, stmt handle.Statement, argumentIndexes [][]int, argumentSlots []any) error {
+	// TODO: consider checking plan.IndexesOfTransparentPointerStructs and returning an error (instead of panicking on FieldByIndex) if pointer struct is nil
+	//       (might want to have bookkeeping to only check pointer structs that lead to PK fields)
 	for idx, index := range argumentIndexes {
 		argumentSlots[idx] = v.FieldByIndex(index).Interface()
 	}
@@ -188,7 +193,7 @@ func deleteRecord(ctx context.Context, v reflect.Value, recordIndex int, stmt ha
 // Upsert executes either an SQL INSERT or UPDATE statement for each of the provided records,
 // based on whether the record already exists in the DB or not.
 //
-//   - For record types that have fields declared with the "auto" tag, INSERT is chosen iff those fields hold zero values.
+//   - For record types that have fields declared with the "auto" tag, INSERT is chosen if and only if those fields hold zero values.
 //     Returns an error if only some of the respective fields hold zero values while others don't.
 //     Returns an error if [NewStore] was called without the [TableNameIs] or [PrimaryKeyIs] options, which are both required to generate the respective queries for this method.
 //   - For record types that do not have fields declared with the "auto" tag, an INSERT ... ON CONFLICT statement is used.