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
