The reason this module never had an underscore (and instead has the "don't use this outside of Twisted" line in the docstring) is because it originated in a time when Twisted was ostensibly split up into multiple projects, and I ill-advisedly decided that it technically needed to be "public" in order for the non-Twisted-core subprojects to use it. That was a silly decision, and given that the docstring has always told people not to use it, please feel free to rename it. -Chris On Mon, Aug 8, 2016, 1:56 AM Craig Rodrigues <rodrigc@crodrigues.org> wrote:
On Sun, Aug 7, 2016 at 11:01 PM, Glyph Lefkowitz <glyph@twistedmatrix.com> wrote:
This is also addressing a real problem. One of the *major* issues with Twisted is *documentation noise*. Developers trying to use Twisted to build things frequently complain about this: they look for an API to do XYZ, and they search the reference documentation, which produces dozens of confusing, irrelevant hits. There are multiple issues that interact here (see, for example, <https://github.com/twisted/pydoctor/issues/49> which is a big part of the problem) but one significant one is that our apparently-public API surface is just too big. Removing things like this, which are really _totally_ useless to anyone, is useful in and of itself and also amplifies the benefit of any other work on docs and tooling to properly segregate public and private API documentation.
Making dist.py private seems to fall under the category of "code cleanliness", and doesn't seem to solve any specific pressing issue that I see. Reducing documentation noise is a good goal, but if dist.py was left the way it is, things would probably be OK with Twisted, and I think people could figure things out in Twisted with respect to the documentation.
Since you mention pydoctor, I will mention two issues, that I feel are more important to the project that moving around dist.py:
- pydoctor produces false errors, specifically in h2 code: https://buildbot.twistedmatrix.com/builders/documentation/builds/1291/steps/... - pydoctor doesn't work on Python 3: https://github.com/twisted/pydoctor/issues/96
I understand that Twisted is a volunteer project, and people can work on whatever they want. I also see on this list, that a few people support the dist.py change, so as long as Adi's change meets the Twisted coding standards, gets code review approval, and can pass all the buildbots, it can move forward, despite my objections.
-- Craig
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python