9461 pydoctor warnings

[twm]

Clear some pydoctor/epytext warnings I noticed while working on #1020. The pywin32 errors appear be legitimate but not fixable, as the ActiveState docs there have disappeared: http://docs.activestate.com/activepython/2.7/pywin32/PyWin32.html is a 404.

Contributor Checklist:

• There is an associated ticket in Trac. https://twistedmatrix.com/trac/ticket/9461
• The changes pass minimal style checks (see: https://twistedmatrix.com/trac/wiki/TwistedDevelopment#GettingYourPatchAccepted )
• I have created a newsfragment in src/twisted/newsfragments/ (see: https://twistedmatrix.com/trac/wiki/ReviewProcess#Newsfiles )
• I have updated the automated tests.

[adiroiban]

Thanks for looking into this.
AFAIK we have a test for documentation and the build should fail if we have pydoctor warnings.
Maybe we can take this opportunity to also fix the test :)

[adiroiban]

So it looks like there is no test to check that we don't introduce new warnings in future PR.
I remember that I worked on this at some time... but not sure how and why it was changed.

---

Or maybe it was done only for buildbot

In buildbot I see that we got errors in step 6, yet the build is green

https://buildbot.twistedmatrix.com/builders/documentation/builds/4014

---

Note that now we also run epydoc build on Circle-CI so maybe as part of TDD process we can look at updating tox -r -e apidocs to fail.

What do you think?

[twm]

@adiroiban I actually wrote the ticket for this with a deliberately narrow scope. Basically, I wanted to fix the warning I introduced.

Since pydoctor warnings are issued based on external resources over which we have no control, I'm not too keen on making them break the build. I feel that it is important that we seek and destroy false positives. I mean, there hasn't been much merged here in the last month, has there? I note that Travis started reporting random failures of twisted.python.test.test_sendmsg.CModuleSendmsgTests.test_shortsend about a month ago. A broken build is discouraging to contributors.

Overall, I would prefer that the perfect not be the enemy of the good. Do these changes look okay to merge?

[codecov]

Codecov Report

Merging #1021 into trunk will decrease coverage by 0.06%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##            trunk    #1021      +/-   ##
==========================================
- Coverage   91.89%   91.83%   -0.07%     
==========================================
  Files         844      842       -2     
  Lines      150605   150339     -266     
  Branches    13142    13145       +3     
==========================================
- Hits       138397   138059     -338     
- Misses      10116    10180      +64     
- Partials     2092     2100       +8

[glyph]

This looks to be unambiguously correct. Please land at your convenience!

[glyph]

This might be more a .misc, to be honest.