docs: Use `JsonableError` instead of `json_error`.

docs/subsystems/logging.md

@@ -32,9 +32,8 @@ infrastructure needed by our error reporting system:
 * A nice framework for filtering passwords and other important user
   data from the exception details, which we use in
   `zerver/filters.py`.
-* Middleware for handling `JsonableError`, our system for allowing
+* Middleware for handling `JsonableError`, which is our standard
-  code anywhere in Django to report an API-facing `json_error` from
+  system for API code to return a JSON-format HTTP error response.
-  anywhere in a view code path.
 
 Since 500 errors in any Zulip server are usually a problem the server
 administrator should investigate and/or report upstream, we have this

docs/tutorials/life-of-a-request.md

@@ -193,9 +193,9 @@ This is covered in good detail in the [writing views doc](writing-views.md).
 ## Results are given as JSON
 
 Our API works on JSON requests and responses. Every API endpoint should
-return `json_error` in the case of an error, which gives a JSON string:
+`raise JsonableError` in the case of an error, which gives a JSON string:
 
-`{'result': 'error', 'msg': <some error message>}`
+`{'result': 'error', 'msg': <some error message>, 'code': 'BAD_REQUEST'}`
 
 in a
 [HTTP response](https://docs.djangoproject.com/en/1.8/ref/request-response/)

docs/tutorials/new-feature-tutorial.md

@@ -437,7 +437,7 @@ can be handled at the beginning of `update_realm`.
     if default_language is not None and default_language not in get_available_language_codes():
         raise JsonableError(_("Invalid language '%s'" % (default_language,)))
     if description is not None and len(description) > 100:
-        return json_error(_("Realm description cannot exceed 100 characters."))
+        raise JsonableError(_("Realm description cannot exceed 100 characters."))
     # ...
 
 The code in `update_realm` loops through the `property_types` dictionary