From f3801b0d9a0035264fe15867193bf2cc65065d51 Mon Sep 17 00:00:00 2001
From: fivetran-catfritz <111930712+fivetran-catfritz@users.noreply.github.com>
Date: Mon, 16 Dec 2024 18:28:56 -0600
Subject: [PATCH] docs/passthrough-explanation

---
 CHANGELOG.md                   |  6 ++++++
 README.md                      |  5 +++--
 macros/add_renamed_columns.sql | 14 +++++++++++++-
 macros/coalesce_rename.sql     | 14 ++++++++++++--
 macros/column_list_to_dict.sql | 14 +++++++++++++-
 5 files changed, 47 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1c88d37..5770986 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,9 @@
+# dbt_salesforce_source version.version
+
+## Documentation
+- Minor README updates
+- Updated macro comments to provide clearer and more detailed explanations of the workflow.
+
 # dbt_salesforce_source v1.1.0
 [PR #48](https://github.com/fivetran/dbt_salesforce_source/pull/48) includes the following updates:
 
diff --git a/README.md b/README.md
index 5d439c1..2325e23 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,6 @@
-<p align="center">
+# Salesforce Source dbt Package ([Docs](https://fivetran.github.io/dbt_salesforce_source/))
+
+<p align="left">
     <a alt="License"
         href="https://github.com/fivetran/dbt_salesforce_source/blob/main/LICENSE">
         <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" /></a>
@@ -13,7 +15,6 @@
         <img src="https://img.shields.io/badge/Fivetran_Quickstart_Compatible%3F-yes-green.svg" /></a>
 </p>
 
-# Salesforce Source dbt Package ([Docs](https://fivetran.github.io/dbt_salesforce_source/))
 ## What does this dbt package do?
 <!--section="salesforce_source_model"-->
 - Cleans, tests, and prepares your Salesforce data from [Fivetran's connector](https://fivetran.com/docs/applications/salesforce) for analysis.
diff --git a/macros/add_renamed_columns.sql b/macros/add_renamed_columns.sql
index 4288df3..7cb8c14 100644
--- a/macros/add_renamed_columns.sql
+++ b/macros/add_renamed_columns.sql
@@ -1,5 +1,17 @@
 {% macro add_renamed_columns(column_list) %}
-{# This macro determines the original names for each column and adds them to the list generated within each `get_*_columns` macro. By default, this macro processes column names by removing underscores and capitalizing each part that follows an underscore. This ensures all necessary columns are available for use in the `coalesce_rename` macro. Additionally, this macro tags each column with its renamed version to maintain tracking. #}
+{# 
+    This macro is a step in a workflow applied across models. It appends camelCase spellings to the list of snake_case spellings generated by the `get_*_columns` macro.  
+    By default, it transforms column names by removing underscores and capitalizing each segment following an underscore.  
+    Additionally, it tags each column with its renamed version to facilitate tracking and consistency.  
+
+    Overview:
+    1. `get_*_columns`: Creates list of snake_case columns for a given source table.  
+        1a. `add_renamed_columns`: Appends camelCase spellings of columns to the list.  
+        1b. `add_pass_through_columns`: Appends columns specified in the passthrough variable to the list.  
+    2. `column_list_to_dict`: Converts the list of columns generated in Step 1 into a dictionary, simplifying subsequent operations.  
+    3. `fill_staging_columns`: Ensures all columns from Step 1 are present in the source table by filling `null` values for any missing columns. For columns with multiple spellings, a `null` column is created for the unused spelling.  
+    4. `coalesce_rename`: Uses the dictionary from `column_list_to_dict` to coalesce a column with its renamed counterpart. This step generates the final column and supports custom arguments for renamed spelling, data type, and alias to override default values.  
+#}
 
 {%- set renamed_columns = [] %}
 
diff --git a/macros/coalesce_rename.sql b/macros/coalesce_rename.sql
index 5b0368c..ef137b7 100644
--- a/macros/coalesce_rename.sql
+++ b/macros/coalesce_rename.sql
@@ -7,8 +7,18 @@
     renamed_column_name=column_dict[column_key]["renamed_column_name"]
     ) %}
 
-{# This macro accomodates Fivetran connectors that keep the original salesforce field naming conventions without underscores #}
-{# Utilizes the dictionary generated by `column_list_to_dict` to coalesce a column with its renamed counterpart, producing the final column. This macro also allows for the passing of a custom renamed spelling, datatype, and alias as arguments to override default values. #}
+{#
+    This macro is the final step in a workflow applied across models. It accommodates Fivetran connectors that retain Salesforce's original field naming conventions, which are camelCase instead of snake_case.
+
+    Overview:
+    1. `get_*_columns`: Creates list of snake_case columns for a given source table.  
+        1a. `add_renamed_columns`: Appends camelCase spellings of columns to the list.  
+        1b. `add_pass_through_columns`: Appends columns specified in the passthrough variable to the list.  
+    2. `column_list_to_dict`: Converts the list of columns generated in Step 1 into a dictionary, simplifying subsequent operations.  
+    3. `fill_staging_columns`: Ensures all columns from Step 1 are present in the source table by filling `null` values for any missing columns. For columns with multiple spellings, a `null` column is created for the unused spelling.  
+    4. `coalesce_rename`: Uses the dictionary from `column_list_to_dict` to coalesce a column with its renamed counterpart. This step generates the final column and supports custom arguments for renamed spelling, data type, and alias to override default values.  
+#}
+
 {%- if original_column_name|lower == renamed_column_name|lower %}
     cast({{ renamed_column_name }} as {{ datatype }}) as {{ alias }}
 
diff --git a/macros/column_list_to_dict.sql b/macros/column_list_to_dict.sql
index 703ff69..7dab9e8 100644
--- a/macros/column_list_to_dict.sql
+++ b/macros/column_list_to_dict.sql
@@ -1,5 +1,17 @@
 {% macro column_list_to_dict(column_list) %}
-{# This macro converts the list of dictionaries generated by the `get_*_columns` macros into a dictionary of dictionaries for use in the `coalesce_rename` macro. This conversion is necessary so that each column dictionary entry can be accessed by a key, rather than iterating through a list. #}
+
+{# 
+    This macro is a step in a workflow applied across models. It converts the list of dictionaries generated by the `get_*_columns` macros into a dictionary of dictionaries for use in the `coalesce_rename` macro. This conversion is necessary so that each column dictionary entry can be accessed by a key, rather than iterating through a list. 
+
+    Overview:
+    1. `get_*_columns`: Creates list of snake_case columns for a given source table.  
+        1a. `add_renamed_columns`: Appends camelCase spellings of columns to the list.  
+        1b. `add_pass_through_columns`: Appends columns specified in the passthrough variable to the list.  
+    2. `column_list_to_dict`: Converts the list of columns generated in Step 1 into a dictionary, simplifying subsequent operations.  
+    3. `fill_staging_columns`: Ensures all columns from Step 1 are present in the source table by filling `null` values for any missing columns. For columns with multiple spellings, a `null` column is created for the unused spelling.  
+    4. `coalesce_rename`: Uses the dictionary from `column_list_to_dict` to coalesce a column with its renamed counterpart. This step generates the final column and supports custom arguments for renamed spelling, data type, and alias to override default values.  
+#}
+
     {%- set column_dict = {} -%}
     {%- for col in column_list -%}
         {%- do column_dict.update({col.name: col}) if not col.is_rename -%}