Class deprecations should be noted in API

[Michael Hudson-Doyle]

From https://twistedmatrix.com/trac/ticket/6760:

When a class is deprecated, a note should be added by pydoctor to the class API description.

An example is POP3Client. A deprecation warning is issued in its __init__ function. But in the API, it is not obvious that the class should not be used. That comment could be put in explicitly but that would be repeating information.

[Michael Hudson-Doyle (mwhudson)]

So the question here is how to tell pydoctor that the class is deprecated. The rest should be easy <wink>

[Jean-Paul Calderone (exarkun)]

Here's one idea:

    from twisted.python.deprecate import deprecated

    @deprecated(...)
    class SomeDeprecatedThing(object):
        ...

Although since the goal of the deprecation should be for this code to result in a warning being emitted:

    from module import SomeDeprecatedThing

possibly the solution needs to be something more like `deprecatedModuleAttribute`.

I guess the important point is that there are two goals to keep in mind for this one API. It needs to cause a `DeprecationWarning` to be emitted when the deprecated API is used and it needs to inform pydoctor that it should annotate some generated documentation with deprecation information.

[Michael Hudson-Doyle (mwhudson)]

Hm. So maybe closing the twisted ticket was too hasty? We could re-purpose it into a "twisted needs an api to mark a class deprecated"... although, is there any reason that deprecatedModuleAttribute isn't sufficient? I don't think pydoctor does anything special with deprecatedModuleAttribute currently, but it could.