Repository: pallets/werkzeug

Issue:
flask.abort() documentation broken
[The documentation for abort()](https://flask.palletsprojects.com/en/1.1.x/api/#flask.abort) contains:

> Raises an HTTPException for the given status code or WSGI application:
> 
> abort(404)  # 404 Not Found
> abort(Response('Hello World'))
> Can be passed a WSGI application or a status code. If a status code is given it’s looked up in the list of exceptions and will raise that exception, if passed a WSGI application it will wrap it in a proxy WSGI exception and raise that:
> 
> abort(404)
> abort(Response('Hello World'))

(with the same example duplicated almost identically).

I find it unclear what the author meant to write. Perhaps a second synopsis was supposed to be there documenting the WSGI application form.


Discussion:
I'm not sure what you mean, everything appears documented.
Well, to start off, the documentation for abort() apparently contains 4 independant examples, but:

1. They are found in only 2 code fragments.
2. None of these is labelled as an example.
I'm sorry, I'm not seeing what's wrong right now, I must be misunderstanding what you're trying to describe. I'm happy to consider a PR if you think there is a clearer wording.
@davidism do you recognize the documentation for abort() contains examples?
As @Chealer noted The 2 examples for [flask.abort](https://flask.palletsprojects.com/en/1.1.x/api/#flask.abort) documentation are nearly identical. The only difference is that the first includes a comment `# 404 Not Found`.

![image](https://user-images.githubusercontent.com/361566/70858002-4436f900-1ec7-11ea-9b90-a02bdc33e8f3.png)

___
It looks like the `flask.abort` documentation is the same as werkzeug's [werkzeug.exceptions.abort](https://werkzeug.palletsprojects.com/en/0.15.x/exceptions/#simple-aborting)

![image](https://user-images.githubusercontent.com/361566/70858013-63358b00-1ec7-11ea-9455-33183942d29f.png)

I believe the 2nd example block in both of these is redundant. If I'm understanding correctly,  `abort(Response('Hello World'))` is an example of passing an "WSGI application" (See [pep-0333 Application/Framework side](https://www.python.org/dev/peps/pep-0333/#id15)).

> The application object is simply a callable object that accepts two arguments. The term "object" should not be misconstrued as requiring an actual object instance: a function, method, class, or instance with a __call__ method are all acceptable for use as an application object. Application objects must be able to be invoked more than once, as virtually all servers/gateways (other than CGI) will make such repeated requests.
 
> If I'm understanding correctly, `abort(Response('Hello World'))` is an example of passing an "WSGI application" (See [pep-0333 Application/Framework side](https://www.python.org/dev/peps/pep-0333/#id15)).

My understanding is the same.
Please open PRs to fix issues in documentation. We've spent more time going back and forth trying to explain what the problem is than it would have taken to submit a trivial PR to remove the redundancy.

Resolving patch:
diff --git a/src/werkzeug/exceptions.py b/src/werkzeug/exceptions.py
--- a/src/werkzeug/exceptions.py
+++ b/src/werkzeug/exceptions.py
@@ -767,17 +767,13 @@ def __call__(self, code, *args, **kwargs):
 
 def abort(status, *args, **kwargs):
     """Raises an :py:exc:`HTTPException` for the given status code or WSGI
-    application::
+    application.
 
-        abort(404)  # 404 Not Found
-        abort(Response('Hello World'))
+    If a status code is given, it will be looked up in the list of
+    exceptions and will raise that exception.  If passed a WSGI application,
+    it will wrap it in a proxy WSGI exception and raise that::
 
-    Can be passed a WSGI application or a status code.  If a status code is
-    given it's looked up in the list of exceptions and will raise that
-    exception, if passed a WSGI application it will wrap it in a proxy WSGI
-    exception and raise that::
-
-       abort(404)
+       abort(404)  # 404 Not Found
        abort(Response('Hello World'))
 
     """


Test patch: