Flask comment/docstring cleanup

Address a few nits in docstrings and comments from the flask conversion
patches.

Change-Id: I058d50168c8e5fa566bd98d7dba101ae9e4f1684
Partial-Bug: #1776504

keystone/api/users.py

@@ -397,7 +397,7 @@ class OAuth1ListAccessTokensResource(_OAuth1ResourceBase):
     def get(self, user_id):
         """List OAuth1 Access Tokens for user.
 
-        GET /v3/users/{user_id}/OS=OAUTH1/access_tokens
+        GET /v3/users/{user_id}/OS-OAUTH1/access_tokens
         """
         ENFORCER.enforce_call(action='identity:list_access_tokens')
         if self.oslo_context.is_delegated_auth:

keystone/server/flask/request_processing/json_body.py

@@ -48,14 +48,22 @@ def json_body_before_request():
                     _('resulting JSON load was not a dict'))
         else:
             # We no longer need enforcement on this API, set unenforced_ok
-            # we already hit a validation error.
+            # we already hit a validation error. This is required as the
+            # request is never hitting the resource methods, meaning
+            # @unenforced_api is not called. Without marking the request
+            # as "unenforced_ok" the assertion check to ensure enforcement
+            # was called would raise up causing a 500 error.
             ks_flask_common.set_unenforced_ok()
             raise exception.ValidationError(attribute='application/json',
                                             target='Content-Type header')
 
     except werkzeug_exceptions.BadRequest:
         # We no longer need enforcement on this API, set unenforced_ok
-        # we already hit a validation error.
+        # we already hit a validation error. This is required as the
+        # request is never hitting the resource methods, meaning
+        # @unenforced_api is not called. Without marking the request
+        # as "unenforced_ok" the assertion check to ensure enforcement
+        # was called would raise up causing a 500 error.
         ks_flask_common.set_unenforced_ok()
         raise exception.ValidationError(attribute='valid JSON',
                                         target='request body')

keystone/server/flask/request_processing/middleware/url_normalize.py

@@ -16,6 +16,9 @@
 class URLNormalizingMiddleware(object):
     """Middleware filter to handle URL normalization."""
 
+    # NOTE(morgan): This must be a middleware as changing 'PATH_INFO' after
+    # the request hits the flask app will not impact routing.
+
     def __init__(self, app):
         self.app = app