What should be considered private in the Index of Names?

[mthuurne]

If you look for successResultOf() in Twisted's Index of Names, you won't see it unless you click "Show Private API". This is because the method lives in twisted.trial._synctest._Assertions, a private class inside a private package.

However, twisted.trial.unittest.SynchronousTestCase is a public re-export of twisted.trial._synctest.SynchronousTestCase, which extends twisted.trial._synctest._Assertions. So via inheritance the successResultOf() method is publicly accessible. Therefore I think it makes sense to consider it public in the Index of Names.

Are there more ways in which a name that is considered private by the current implementation should actually be considered public instead?

[adiroiban]

I think inheritance is the only implicit way.

[mthuurne]

A different approach would be to not make twisted.trial._synctest._Assertions.successResultOf() public, but to create a placeholder named twisted.trial.unittest.SynchronousTestCase.successResultOf(), which shows the info of the inherited method but is a public name.

An advantage to this approach is that we could include that public name in the intersphinx inventory, so external docs would not have to link to an implementation class.

[adiroiban]

So... to reproduce this "issue"

You got to https://docs.twistedmatrix.com/en/latest/api/twisted.trial.unittest.SynchronousTestCase.html

The successResultOf is listed as Inherited from _Assertions: and if you click it, it goes to what looks like private module.

Expected result. Please correct me if I am wrong. Listed as direct implementation and not as inherited. Clicking on it will stay on the same page. The content is the same as from _Assertions. Clicking on "Show source" will got ot _Assertions class.

[tristanlatr]

Related issue: #50