docs: move feedback.rst sections around

docs/how_tos/feedback.rst

@@ -26,6 +26,79 @@ them to the feedback module to show the user a nicely formatted error.
    :depth: 1
 
 
+How does the feedback module work?
+----------------------------------
+
+Via exceptions
+~~~~~~~~~~~~~~
+
+* `payment/data/service.js`_ catches most exceptions thrown by the Axios client
+  calling the APIs and runs `handleBasketApiError()`_
+
+* `handleBasketApiError()`_ calls `payment/data/handleRequestError.js`_, which
+  reformats and transforms the feedback module JSON and re-throws the error.
+
+* `payment/data/sagas.js`_ catches most errors thrown by
+  `payment/data/service.js`_ and calls `feedback/data/sagas.js`_
+  `handleErrors()`_.
+
+* `handleErrors()`_ uses the ``addMessage()`` action and the associated
+  `addMessage() reducer helper function`_ to store the feedback message in
+  Redux's store.
+
+* `feedback/AlertList.jsx`_ is connected to the Redux store and formats each
+  feedback message into the props of a new `feedback/AlertMessage.jsx`_.
+
+.. _addMessage() reducer helper function: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/feedback/data/reducers.js#L22-L34
+.. _feedback/AlertList.jsx: https://github.com/openedx/frontend-app-payment/blob/master/src/feedback/AlertList.jsx
+.. _feedback/AlertMessage.jsx: https://github.com/openedx/frontend-app-payment/blob/master/src/feedback/AlertMessage.jsx
+
+.. _Via messages:
+
+Via messages
+~~~~~~~~~~~~
+
+* `payment/data/sagas.js`_ passes selected API responses into
+  `handleMessages()`_.
+
+* `handleMessages()`_ works similarly to `handleErrors()`_. See above.
+
+.. _handleMessages(): https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/feedback/data/sagas.js#L39
+
+
+How do I add a new error message in the payment module?
+-------------------------------------------------------
+
+* In `payment/data/service.js`_, add ``.catch(handleBasketApiError)`` to the
+  method chain of the Axios request (usually ``post()`` or ``get()``) to
+  reformat the error into the correct format, then rethrow.
+
+    * `handleBasketApiError()`_ is a thin wrapper around
+      `payment/data/handleRequestError.js`_.
+
+* In `payment/data/sagas.js`_, add a try-catch that catches the error
+  reformatted and rethrown by `handleBasketApiError()`_ and calls the
+  appropriate error handler:
+
+    * ``yield call(handleErrors, error, clearExistingMessages)`` for the
+      `List of errors`_ or `Single error`_ formats
+    * ``yield call(handleReduxFormValidationErrors, error,
+      clearExistingMessages)`` for the `Dictionary of field errors`_ format
+
+* In `payment/AlertCodeMessages.jsx`_, add a new component for your message.
+
+* In `components/formatted-alert-list/FormattedAlertList.jsx`_, add the new
+  component you created in ``<AlertCodeMessages>`` to ``messagesCode`` under
+  key named after the ``error_code`` you want the API to call to trigger this
+  error message.
+
+.. _payment/data/service.js: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/payment/data/service.js
+.. _payment/data/handleRequestError.js: https://github.com/openedx/frontend-app-payment/blob/master/src/payment/data/handleRequestError.js
+.. _payment/data/sagas.js: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/payment/data/sagas.js
+.. _payment/AlertCodeMessages.jsx: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/payment/AlertCodeMessages.jsx
+.. _components/formatted-alert-list/FormattedAlertList.jsx: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/components/formatted-alert-list/FormattedAlertList.jsx
+
+
 What should the API do?
 -----------------------
 
@@ -210,44 +283,15 @@ Some error codes are connected to pre-built components. See:
 .. _AlertCodeMessages: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/payment/AlertCodeMessages.jsx
 
 
-How does the feedback module work?
-----------------------------------
-
-Via exceptions
-~~~~~~~~~~~~~~
-
-* `payment/data/service.js`_ catches most exceptions thrown by the Axios client
-  calling the APIs and runs `handleBasketApiError()`_
-
-* `handleBasketApiError()`_ calls `payment/data/handleRequestError.js`_, which
-  reformats and transforms the feedback module JSON and re-throws the error.
-
-* `payment/data/sagas.js`_ catches most errors thrown by
-  `payment/data/service.js`_ and calls `feedback/data/sagas.js`_
-  `handleErrors()`_.
-
-* `handleErrors()`_ uses the ``addMessage()`` action and the associated
-  `addMessage() reducer helper function`_ to store the feedback message in
-  Redux's store.
-
-* `feedback/AlertList.jsx`_ is connected to the Redux store and formats each
-  feedback message into the props of a new `feedback/AlertMessage.jsx`_.
-
-.. _addMessage() reducer helper function: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/feedback/data/reducers.js#L22-L34
-.. _feedback/AlertList.jsx: https://github.com/openedx/frontend-app-payment/blob/master/src/feedback/AlertList.jsx
-.. _feedback/AlertMessage.jsx: https://github.com/openedx/frontend-app-payment/blob/master/src/feedback/AlertMessage.jsx
-
-.. _Via messages:
-
-Via messages
-~~~~~~~~~~~~
-
-* `payment/data/sagas.js`_ passes selected API responses into
-  `handleMessages()`_.
+What is the fallback error?
+---------------------------
 
-* `handleMessages()`_ works similarly to `handleErrors()`_. See above.
+If a saga calls `handleErrors()`_ but the API response is not in one of the
+formats above or ``error_code`` is ``fallback-error``, ``handleErrors()`` will
+throw up the `FallbackErrorMessage`_.
 
-.. _handleMessages(): https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/feedback/data/sagas.js#L39
+.. _FallbackErrorMessage: https://github.com/openedx/frontend-app-payment/blob/master/src/feedback/FallbackErrorMessage.jsx
+.. _handleErrors(): https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/feedback/data/sagas.js#L10C22-L10C22
 
 
 How to clear the list of feedback?
@@ -279,50 +323,6 @@ See the `URL parameter error message implementation`_.
 .. _URL parameter error message implementation: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/feedback/data/sagas.js#L49-L53
 
 
-How do I add a new error message in the payment module?
--------------------------------------------------------
-
-* In `payment/data/service.js`_, add ``.catch(handleBasketApiError)`` to the
-  method chain of the Axios request (usually ``post()`` or ``get()``) to
-  reformat the error into the correct format, then rethrow.
-
-    * `handleBasketApiError()`_ is a thin wrapper around
-      `payment/data/handleRequestError.js`_.
-
-* In `payment/data/sagas.js`_, add a try-catch that catches the error
-  reformatted and rethrown by `handleBasketApiError()`_ and calls the
-  appropriate error handler:
-
-    * ``yield call(handleErrors, error, clearExistingMessages)`` for the
-      `List of errors`_ or `Single error`_ formats
-    * ``yield call(handleReduxFormValidationErrors, error,
-      clearExistingMessages)`` for the `Dictionary of field errors`_ format
-
-* In `payment/AlertCodeMessages.jsx`_, add a new component for your message.
-
-* In `components/formatted-alert-list/FormattedAlertList.jsx`_, add the new
-  component you created in ``<AlertCodeMessages>`` to ``messagesCode`` under
-  key named after the ``error_code`` you want the API to call to trigger this
-  error message.
-
-.. _payment/data/service.js: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/payment/data/service.js
-.. _payment/data/handleRequestError.js: https://github.com/openedx/frontend-app-payment/blob/master/src/payment/data/handleRequestError.js
-.. _payment/data/sagas.js: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/payment/data/sagas.js
-.. _payment/AlertCodeMessages.jsx: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/payment/AlertCodeMessages.jsx
-.. _components/formatted-alert-list/FormattedAlertList.jsx: https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/components/formatted-alert-list/FormattedAlertList.jsx
-
-
-What is the fallback error?
----------------------------
-
-If a saga calls `handleErrors()`_ but the API response is not in one of the
-formats above or ``error_code`` is ``fallback-error``, ``handleErrors()`` will
-throw up the `FallbackErrorMessage`_.
-
-.. _FallbackErrorMessage: https://github.com/openedx/frontend-app-payment/blob/master/src/feedback/FallbackErrorMessage.jsx
-.. _handleErrors(): https://github.com/openedx/frontend-app-payment/blob/1d631c51035eb8405ce9b03e0fa64a5a6e386268/src/feedback/data/sagas.js#L10C22-L10C22
-
-
 When are snake_case dictionary keys auto-converted to camelCase?
 ----------------------------------------------------------------