From 958e98debdfcc99156c1a2b3db33dc53add5f3c7 Mon Sep 17 00:00:00 2001
From: Maikel Linke <maikel@email.org.au>
Date: Fri, 22 Feb 2019 14:01:22 +1100
Subject: [PATCH] Document stock validation of variant overrides

---
 .../stock_settings_override_validation.rb      | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/app/models/concerns/stock_settings_override_validation.rb b/app/models/concerns/stock_settings_override_validation.rb
index b9e3624aec..b548a8b64b 100644
--- a/app/models/concerns/stock_settings_override_validation.rb
+++ b/app/models/concerns/stock_settings_override_validation.rb
@@ -1,3 +1,21 @@
+# Validates the combination of on_demand and count_on_hand values.
+#
+# `on_demand` can have three values: true, false or nil
+# `count_on_hand` can either be: nil or a number
+#
+# This means that a variant override can be in six different stock states
+# but only three of them are valid.
+#
+# | on_demand | count_on_hand | stock_overridden? | use_producer_stock_settings? | valid? |
+# |-----------|---------------|-------------------|------------------------------|--------|
+# | 1         | nil           | false             | false                        | true   |
+# | 0         | x             | true              | false                        | true   |
+# | nil       | nil           | false             | true                         | true   |
+# | 1         | x             | ?                 | ?                            | false  |
+# | 0         | nil           | ?                 | ?                            | false  |
+# | nil       | x             | ?                 | ?                            | false  |
+#
+# This module has one method for each invalid case.
 module StockSettingsOverrideValidation
   extend ActiveSupport::Concern