Expand type: ignore documentation

[tusharsadhwani]

Feature

Allowing a short message with your type ignore comments, for better context

Pitch

I wanted to add a little comment with my type: ignore to provide some context as to why that ignore is present in the code.

This is the thing that I tried:

for text in iter(buff.read1, b""):  # type: ignore - typeshed bug
    print(decoder.decode(text), end="")

Unfortunately that doesn't work.
I tried a few other variants, like # type: ignore; typeshed bug, but I could find no way to add a message to the ignore comment.

It also seems like an easy feature that I could work on :)

[emmatyping]

Per PEP 484:

In some cases, linting tools or other comments may be needed on the same line as a type comment. In these cases, the type comment should be before other comments and linting markers:

# type: ignore # <comment or other marker>

[tusharsadhwani]

I wish this was mentioned in mypy docs... perhaps in this section

[emmatyping]

It is (briefly) covered here, but almost as an aside https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html#when-you-re-puzzled-or-when-things-are-complicated

If you want to suggest a change in a PR I'm happy to take a look, but I think the bigger issue is we don't really talk much about # type: ignore in the typesystem reference to begin with. It might be useful to add a section about # type: ignore to this page: https://mypy.readthedocs.io/en/stable/type_inference_and_annotations.html#type-inference-and-type-annotations