Review fixes

Author: mnocon

docs/discounts/discounts_api.md

@@ -30,26 +30,46 @@ Discounts are applied in two places, listed in the [`DiscountType`](/api/php_api
 Regardless of activation place, discounts always apply to products and reduce their base price.
 
 To define when a discount activates and how the price is reduced, use rules and conditions.
-They make use of the [Symfony Expression language]([[= symfony_doc=]]//components/expression_language.html).
-Use the expression values provided below when using data migrations or when parsing REST API responses.
+They use the [Symfony Expression language]([[= symfony_doc=]]/components/expression_language.html) to express their logic.
 
 ### Rules
 
-Discount rules define how the calculate the price reduction.
+Discount rules define how to calculate the price reduction.
 The following discount rule types are available in the `\Ibexa\Discounts\Value\DiscountRule` namespace:
 
-| Rule type<br>(identifier) | Description | Expression value |
+| Rule type<br>(identifier) | Description | Required expression value |
 |---|---|---|
 | `FixedAmount`<br><nobr>(`fixed_amount`)</nobr> | Deducts the specified amount, for example <nobr>10 EUR</nobr>, from the base price | <nobr>`discount_amount`</nobr> |
 | `Percentage`<br><nobr>(`percentage`)</nobr> | Deducts the specified percentage, for example -10%, from the base price | <nobr>`discount_percentage`</nobr> |
 
 Only a single discount can be applied to a given product, and a discount can only have a single rule.
 
+When creating a rule through other means than the user interface, you must pass the required expression values for the rule to be valid:
+
+- using PHP, the values are passed through the constuctor which converts them into an expression variable
+- using data migrations and the REST API, the values are specified using the `expressionValues` key
+
+See the following examples for data migrations and the REST API usage:
+
+- creating discounts with [data migrations](importing_data.md#discounts):
+
+``` yaml hl_lines="4-7"
+[[= include_file('code_samples/data_migration/examples/discounts/discount_create.yaml', 0, 2) =]]# ...
+[[= include_file('code_samples/data_migration/examples/discounts/discount_create.yaml', 18, 22) =]]
+```
+
+- parsing responses from the [REST API](https://doc.ibexa.co/en/4.6/api/rest_api/rest_api_reference/rest_api_reference.html#discounts):
+
+``` json hl_lines="16-21"
+[[= include_file('docs/api/rest_api/rest_api_reference/input/examples/discounts/Discount.json.example', 0, 21) =]]
+[[= include_file('docs/api/rest_api/rest_api_reference/input/examples/discounts/Discount.json.example', 44, 45) =]]
+```
+
 ### Conditions
 
 With conditions you can narrow down the scenarios in which the discount applies. The following conditions are available in the `\Ibexa\Discounts\Value\DiscountCondition` and `\Ibexa\DiscountsCodes\Value\DiscountCondition` namespaces:
 
-| Condition<br>(identifier) | Applies to | Description | Expression values |
+| Condition<br>(identifier) | Applies to | Description | Required expression values |
 |---|---|---|---|
 | <nobr>`IsInCategory`</nobr><br><nobr>(`is_in_category`)</nobr> | Cart, Catalog | Checks if the product belongs to specified [product categories]([[= user_doc =]]/pim/work_with_product_categories) | `categories` |
 | <nobr>`IsInCurrency`</nobr><br><nobr>(`is_in_currency`)</nobr> | Cart, Catalog | Checks if the product has price in the specified currency | <nobr>`currency_code`</nobr> |
@@ -62,6 +82,27 @@ With conditions you can narrow down the scenarios in which the discount applies.
 
 When multiple conditions are specified, all of them must be met.
 
+As with rules, when creating a condition through other means than the user interface, you must pass the required expression values for the condition to be valid:
+
+- using PHP, the values are passed through the constuctor which converts them into an expression variable
+- using data migrations and the REST API, the values are specified using the `expressionValues` key
+
+See the following examples for data migrations and the REST API usage:
+
+- creating discounts with [data migrations](importing_data.md#discounts):
+
+``` yaml hl_lines="4-14"
+[[= include_file('code_samples/data_migration/examples/discounts/discount_create.yaml', 0, 2) =]]# ...
+[[= include_file('code_samples/data_migration/examples/discounts/discount_create.yaml', 22, 33) =]]
+```
+
+- parsing responses from the [REST API](https://doc.ibexa.co/en/4.6/api/rest_api/rest_api_reference/rest_api_reference.html#discounts):
+
+``` json hl_lines="16-23"
+[[= include_file('docs/api/rest_api/rest_api_reference/input/examples/discounts/Discount.json.example', 0, 15) =]][[= include_file('docs/api/rest_api/rest_api_reference/input/examples/discounts/Discount.json.example', 21, 29) =]]
+[[= include_file('docs/api/rest_api/rest_api_reference/input/examples/discounts/Discount.json.example', 44, 45) =]]
+```
+
 ### Priority
 
 You can set discount priority as a number between 1 and 10 to indicate which discount should have [higher priority](discounts_guide.md#discounts-priority) when choosing the one to apply.

docs/discounts/discounts_guide.md

@@ -96,6 +96,13 @@ You can also limit this choice to a subset of products:
 
 #### Conditions
 
+Use conditions to limit the applicability of a discount, for example by checking that:
+
+- the product belongs to a specific category
+- the customer belongs to a specific customer group
+
+before applying the discount.
+
 For **cart discounts**, you can specify additional conditions that must be met for the discount to apply.
 
 These conditions can include:
@@ -104,6 +111,8 @@ These conditions can include:
 - minimum purchase amount (total cart value)
 - special [discount codes](#discount-codes)
 
+See [the built-in list of conditions](discounts_api.md#conditions) and [creating custom conditions](extend_discounts.md#implement-custom-condition) for more information.
+
 ##### Discount codes
 
 For **cart discounts**, you can specify an additional text value that needs to be entered in the cart for the discount to apply.

docs/discounts/extend_discounts.md

@@ -20,26 +20,28 @@ Together with the existing [events](event_reference.md) and the [Discounts PHP A
 
 ## Create custom conditions and rules
 
-With custom [conditions](discounts_api.md#conditions) you can create more advanced discounts that apply only in specific scenarios.
+With custom [conditions](discounts_api.md#conditions) and [rules](discounts_api.md#rules) you can create more advanced discounts that apply only in specific scenarios.
 
-The logic for both the conditions and rules is specified using [Symfony's expression language](https://symfony.com/doc/current/components/expression_language.html).
+For both of them, you need to specify their logic with [Symfony's expression language](https://symfony.com/doc/current/components/expression_language.html).
 
 ### Available expressions
 
-The following expressions are available for conditions and rules:
+You can use the following built-in expressions (variables and functions) in your own custom conditions and rules.
+You can also [create your own](#custom-expressions).
 
 | Type | Name | Value | Available for | 
 | --- | --- | --- | --- |
 | Function | `get_current_region()` | [Region object](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-RegionInterface.html) of the current siteaccess.| Conditions, rules |
 | Function | `is_in_category()` | `true/false`, depending if a product belongs to given [product categories](pim_guide.md#product-categories).| Conditions, rules |
 | Function | `is_user_in_customer_group()` | `true/false`, depending if an user belongs to given [customer groups](customer_groups.md). | Conditions, rules |
 | Function | `calculate_purchase_amount()` | Purchase amount, calculated for all products in the cart before the discounts are applied.| Conditions, rules |
-| Function | <nobr>`is_product_in_product_codes()`</nobr> | `true/false`, depending if the product is part of the given list.| Conditions, rules |
+| Function | <nobr>`is_product_in_product_codes()`</nobr> | Parameters: <br> - [Product object](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-ProductInterface.html)<br>- array of product codes<br> Returns `true` if the product is part of the given list.| Conditions, rules |
+| Function | <nobr>`is_valid_discount_code()`</nobr> | Parameter: discount code (string). <br> Returns `true` if the discount code is valid for current user.| Conditions, rules |
 | Variable | `cart` | [Cart object](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Cart-Value-CartInterface.html) associated with current context.| Conditions, rules |
 | Variable | `currency` | [Currency object](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-CurrencyInterface.html) of the current siteaccess. | Conditions, rules |
 | Variable | `customer_group` | [Customer group object](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-CustomerGroupInterface.html) associated with given price context or the current user.| Conditions, rules |
+| Variable | `product` | [Product object](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-ProductInterface.html)| Conditions, rules |
 | Variable | `amount` | Original price of the product | Rules |
-| Variable | `product` | [Product object](/api/php_api/php_api_reference/classes/Ibexa-Contracts-ProductCatalog-Values-ProductInterface.html)| Rules |
 
 ### Custom expressions
 
@@ -101,18 +103,27 @@ In a production implementation, you should consider refactoring the `current_use
 
 ### Implement custom condition
 
-The following example creates a new discount condition. It allows you to offer a special discount for customers on the date when their account was created, making use of the expressions added above.
-
-The `tolerance` option allows you to make the discount usable for a longer period of time (for example, a day before or after the registration date) to allow more time for the customers to use it.
+The following example creates a new discount condition.
+It allows you to offer a special discount for customers on the date when their account was created, making use of the expressions added above.
 
 Create the condition by creating a class implementing the [`DiscountConditionInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-DiscountConditionInterface.html):
 
-``` php
+``` php hl_lines="29-32"
 [[= include_file('code_samples/discounts/src/Discounts/Condition/IsAccountAnniversary.php') =]]
 ```
 
+This condition can be used in both catalog and cart discounts.
+To implement a cart-only discount, additionally implement the marker [`CartDiscountConditionInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-CartDiscountConditionInterface.html) interface.
+
 The `tolerance` option is made available for usage in the expression by passing it in the constructor.
-The expression can evaluate to `true` or `false` depending on the custom expressions values.
+The `getExpression` method contains the logic of the condition, expressed using the variables and functions available in the expression engine.
+The expression must evaluate to `true` or `false`, indicating whether the condition is met.
+
+The example uses three expressions:
+
+- the custom `is_anniversary` function, returning a value indicating whether today is user's registration anniversary
+- the custom `current_user_registration_date` variable, holding the value of current user's registration date
+- the custom `tolerance` variable, holding the acceptable tolerance (in days) for the calculation
 
 For each custom condition class, you must create a dedicated condition factory, a class implementing the `\Ibexa\Discounts\Repository\DiscountCondition\DiscountConditionFactoryInterface` inteface.
 
@@ -131,7 +142,16 @@ Mark it as a service using the `ibexa.discounts.condition.factory` service tag a
                 discriminator: !php/const App\Discounts\Condition\IsAccountAnniversary::IDENTIFIER
 ```
 
-You can now use the condition using the PHP API.
+You can now use the condition, for example by using the PHP API or data migrations:
+
+``` yaml hl_lines="16-19"
+[[= include_file('code_samples/data_migration/examples/discounts/discount_create.yaml', 0, 2) =]]# ...
+[[= include_file('code_samples/data_migration/examples/discounts/discount_create.yaml', 22, 33) =]]
+        -
+            identifier: is_account_anniversary
+            expressionValues:
+                tolerance: 5
+```
 
 To learn how to integrate it into the back office, see [Extend Discounts wizard](extend_discounts_wizard.md).
 
@@ -142,11 +162,19 @@ You could use it, for example, in regions sharing the same currency and apply th
 
 To implement a custom rule, create a class implementing the [`DiscountRuleInterface`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-DiscountRuleInterface.html).
 
-
-``` php
+``` php hl_lines="35-38"
 [[= include_file('code_samples/discounts/src/Discounts/Rule/PurchasingPowerParityRule.php') =]]
 ```
 
+The `getExpression` method contains the logic of the rule, expressed using the variables and functions available in the expression engine.
+The expression must return the new price of the product.
+
+It uses three expressions:
+
+- the built-in `amount` variable, holding the purchase amount
+- the built-in `get_current_region()` function, returning the current region
+- a custom `power_parity_map` variable, holding the purchasing power partity map. It's defined in the constuctor.
+
 As with conditions, create a dedicated rule factory:
 
 ``` php

docs/discounts/extend_discounts_wizard.md

@@ -32,7 +32,18 @@ They include:
 - [`mapUpdateDataToStruct()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountFormMapperInterface.html#method_mapUpdateDataToStruct) creates the [`DiscountUpdateStruct`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-Struct-DiscountUpdateStruct.html) object to update the discount
 - [`mapEditTranslateDataToStruct()`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-DiscountFormMapperInterface.html#method_mapEditTranslateDataToStruct) creates the [`TranslationStruct`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Discounts-Value-Struct-DiscountTranslationStruct.html) objects for [translating the discounts](discounts_api.md#discount-translations)
 
-In addition to these methods, the main form mapper and the form mappers responsible for each step in the wizard dispatch events that you can use to add your custom logic.
+In the UI, the discounts wizard consists of several steps:
+
+- General properties
+- Target group
+- Products
+- Conditions (only for Cart discounts)
+- Discount value
+- Summary
+
+Each of these steps is represented by its own form mappers, data classes, and form types in the code.
+
+In addition, the main form mapper and the form mappers responsible for each step in the wizard dispatch events that you can use to add your custom logic.
 See [discount's form events](discounts_events.md#form-events) for a list of the available events.
 
 ## Integrate custom conditions