[RFC] Deprecate Blueprint.doc decorator

Nobody has claimed this yet.

The `Blueprint.doc` decorator is meant to add documentation that can't be inferred from the code or added by dedicated decorators. It allows the user to pass manual documentation that will be deep-merged with the automatically generated documentation. Unfortunately, it is not the silver bullet one would expect. It suffers from a few intrinsic issues.

We could try to play smart and improve the way the structure received by `doc` is used, but I'd rather add dedicated decorators or other explicit means to allow the user to pass documentation in a structured fashion, with a clear and thin abstraction layer.

I'd like to use this issue to list known issues about `Blueprint.doc` and use cases that should be covered by other means. The goal being to make it useless, and to deprecate it if possible.

### Known issues

- It can't really document arguments as deep-merging lists doesn't work so it conflicts with auto-generated documentation.
- When adding extra documentation for a response, the user must use the same type for the status code than the one used in the `response` decorator (https://github.com/marshmallow-code/flask-smorest/issues/60#issuecomment-487856593).
- It doesn't handle the OASv2 / v3 transparently, while the other decorators are pretty good at it, allowing the user to change the OAS version with a configuration parameter using the same codebase. For instance, it doesn't add `['content']['application/json']` when using v3 which makes it more verbose to the user.

### Use cases

- [x] Add summary/description: Those can be passed in the view function docstring.
- [x] Add examples: Can now be achieved with `response`/`arguments` decorators.
- [ ] Document specific API features (e.g. security information). Since this is quite specific, I think it could be done by a custom decorator defined in user code. Typically, when using a decorator to manage accesses to resources (generally from a flask third-party library), this decorator should be wrapped in a custom decorator that adds the information to the docs (see https://github.com/marshmallow-code/flask-smorest/issues/36#issuecomment-460826257 for an example). This means the `_apidoc` attribute mechanism becomes public API.
- [x] Document / add extra-information to parameters. The only real need was for path parameters. Documentation for path parameters can be passed in `Blueprint.route`. (See #23)
- [x] Document / add extra-information to responses. We could add a specific decorator for that. If we assume a view function can only have one normal response and other responses are errors (or error-likes such as redirections or "not modified"), then that decorator could be called "error". (See #44)

Start by reviewing the Blueprint.doc entry point alongside the response, arguments, and route decorators that already cover the listed use cases. Map the remaining security-documentation case to the public _apidoc mechanism, then determine whether dedicated alternatives cover all cases and whether Blueprint.doc can be deprecated.

Written by the indexing model from the issue text.