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 <rodr...@crodrigues.org> wrote: > On Sun, Aug 7, 2016 at 11:01 PM, Glyph Lefkowitz <gl...@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/api-documentation/logs/pydoctor%20errors > - 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 >
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python