From f662e6ca602930d2bb7bcfd19f9bd45d54e5a23e Mon Sep 17 00:00:00 2001
From: Marcello Stanisci <stanisci.m@gmail.com>
Date: Mon, 11 Mar 2019 12:09:59 +0100
Subject: Finish Doxygen-commenting middleware.py.

---
 talerbank/app/middleware.py | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

(limited to 'talerbank/app/middleware.py')

diff --git a/talerbank/app/middleware.py b/talerbank/app/middleware.py
index 6bd129d..214a21e 100644
--- a/talerbank/app/middleware.py
+++ b/talerbank/app/middleware.py
@@ -21,10 +21,15 @@ class ExceptionMiddleware:
     # Init constructor.
     #
     # @param self the object itself.
-    # @param get_response FIXME TBD.
+    # @param get_response a Django-provided callable that calls
+    #        whatever comes next in the chain: a further middleware
+    #        or the view itself (please refer to the official
+    #        documentation for more details).
     def __init__(self, get_response):
         self.get_response = get_response
 
+        # List of all the exceptions that are managed by
+        # this module.
         self.excs = {
             BankAccount.DoesNotExist: 0,
             BankTransaction.DoesNotExist: 1,
@@ -38,31 +43,45 @@ class ExceptionMiddleware:
             LoginFailed: 12,
             RejectNoRightsException: 13}
 
+
+        # List of all the HTTP endpoint that are likely
+        # to generate exceptions.
         self.apis = {
             "/reject": 5300,
             "/history": 5200,
             "/admin/add/incoming": 5100}
 
+
+        # Map between endpoints and Web pages to render
+        # after the exception gets managed.
         self.render = {
             "/profile": "profile",
             "/register": "index",
             "/public-accounts": "index",
             "/pin/verify": "profile"}
 
-
+    ##
+    # This function is transparently invoked by Django when
+    # a request traverses the chain made of middleware classes
+    # and the view itself as the last element in the chain.
+    #
+    # @param self this class.
+    # @param request Django-specific request object (of the same
+    #        type that is handed to views).
+    # @return Django-specific response object.
     def __call__(self, request):
         return self.get_response(request)
 
-
     ##
     # Main logic for processing the exception.  It checks
     # if the exception captured can be managed, and does it
     # if so.  Otherwise, it lets the native handler operate.
     #
-    # @param a @a ExceptionMiddleware object.
+    # @param self a @a ExceptionMiddleware object.
     # @param request Django-specific HTTP request.
     # @param exception the exception raised from the bank.
     def process_exception(self, request, exception):
+
         # See if we manage this exception.  Return None if not.
         exc_class = None
         for e in self.excs:
@@ -78,6 +97,9 @@ class ExceptionMiddleware:
         # The way error codes compose matches
         # definitions found in [1].
         taler_ec += self.apis.get(request.path, 1000)
+
+        # Check if the endpoint should cause a human-readable
+        # page to be returned.
         render_to = self.render.get(request.path)
         if not render_to:
             return JsonResponse({"ec": taler_ec,
-- 
cgit v1.2.3