twisted.mail.pop3client.__all__ should be empty, so API docs list those objects in correct module

[Itamar Turner-Trauring]

​https://twistedmatrix.com/documents/current/api/twisted.mail.pop3.html doesn't list AdvancedPOP3Client. This is wrong. The reason is that pydoctor wants objects to only be in one module's __all__, and it already appears in pop3client; the same is true of the exception classes there.

pop3client is basically an implementation module of pop3, and should probably be private, so its __all__ should be empty.

[esacteksab]

all = []

all is empty. Too simple?

[Tom Prince]

Unfortunately, doing this changes the public api of twisted.mail.pop3client, which is a backwards incompatible change.

However, it should be possible to tell pydoctor that nothing should be documented here, without changing the api. Perhaps something like

__hidden_all__ = ['some', 'stuff']
__all__ = __hidden_all__'

Assigning to mwhudson, as the pydoctor expert.

In any case, a ticket should be filed to deprecate pop3client, and move everything in it to a private module. (Perhaps moving things to a private module and just importing them in t.m.pop3client is enough to get the documentation in the right place.

[Jean-Paul Calderone]

This sounds like a gross hack.

The contents of __all__ don't actually matter to most programs. Supporting "from ... import *" where "..." is a Twisted module should explicitly be documented as not supported, if it is not already, because it is already likely to result in things breaking when new names are introduced.

So, I don't think these extra hoops are necessary. If we want to remove everything from __all__ we can do that.