Merge pull request #2557 from Matt-Yorkley/pi/class_descriptions

Class descriptions for Product Import

app/models/product_import/entry_processor.rb

@@ -1,3 +1,7 @@
+# This class handles the saving of new product, variant, and inventory records created during
+# product import. It also collates data regarding this process for user feedback, as the import
+# is processed in small stages sequentially over a number of requests.
+
 module ProductImport
   class EntryProcessor
     attr_reader :inventory_created, :inventory_updated, :products_created, :variants_created, :variants_updated, :products_reset_count, :supplier_products, :total_supplier_products

app/models/product_import/entry_validator.rb

@@ -1,3 +1,7 @@
+# This class handles a number of custom validation processes that take place during product import,
+# as a spreadsheet entry is checked to see if it is a valid product, variant, or inventory item.
+# It also handles error messages and user feedback for the validation process.
+
 module ProductImport
   class EntryValidator
     def initialize(current_user, import_time, spreadsheet_data, editable_enterprises, inventory_permissions, reset_counts, import_settings)

app/models/product_import/product_importer.rb

@@ -1,3 +1,10 @@
+# This is the main class for product import. It handles the initial processing of the CSV file,
+# and begins the processing of the spreadsheet entries by the other product import classes.
+# As spreadsheets can contain any number of entries (1000+), the import is split into smaller chunks
+# of 100 items, and processed sequentially over a number of requests to avoid server timeouts.
+# The various bits of collated information such as file upload status, per-item errors or user feedback
+# on the saving process are made available to the controller through this object.
+
 require 'roo'
 
 module ProductImport

app/models/product_import/spreadsheet_data.rb

@@ -1,3 +1,10 @@
+# This class encapsulates a number of "indexes" used during product import. These contain hashes
+# of information that need to be accessed at various stages of the import, and are built in order
+# to minimise the number of queries that take place. So for instance, if a spreadsheet has 4000
+# products for 5 different enterprises and we need to check the enterprise permissions for each
+# product during validation, we have a small index for that data that gets built at the beginning
+# so we don't have to make 4000 queries.
+
 module ProductImport
   class SpreadsheetData
     def initialize(entries)

app/models/product_import/spreadsheet_entry.rb

@@ -1,3 +1,7 @@
+# Objects of this class represent a line from a spreadsheet that will be processed and used
+# to create either product, variant, or inventory records. These objects are referred to as
+# "entry" or "entries" throughout product import.
+
 module ProductImport
   class SpreadsheetEntry
     extend ActiveModel::Naming

app/models/product_import/unit_converter.rb

@@ -1,3 +1,13 @@
+# This class handles conversion of human-readable unit weights for products/variants into
+# the non-human-readable format needed by the database. The table below shows how fields
+# from a spreadsheet (left) become database fields (right):
+#
+# units  unit_type  variant_unit_name   ->    unit_value  variant_unit_scale   variant_unit
+# 250      ml          nil              ->       0.25        0.001               volume
+# 50       g           nil              ->       50          1                   weight
+# 2        kg          nil              ->       2000        1000                weight
+# 1        nil         bunches          ->       1           nil                 items
+
 module ProductImport
   class UnitConverter
     def initialize(attrs)
@@ -12,12 +22,6 @@ module ProductImport
     private
 
     def convert_custom_unit_fields
-      # units unit_type variant_unit_name   ->    unit_value  variant_unit_scale   variant_unit
-      # 250     ml       nil      ....              0.25        0.001               volume
-      # 50      g        nil      ....              50          1                   weight
-      # 2      kg        nil      ....              2000        1000                weight
-      # 1      nil       bunches  ....              1           null                items
-
       init_unit_values
 
       assign_weight_or_volume_attributes if units_and_unit_type_present?