Fix documentation of non-existing parameters #1485
Conversation
This avoids a warning from pydoctor, which expects an '@type' field in a function to match a parameter, not an instance variable.
The name was incorrect for the var-keyword parameter. The type was incorrect as well: for the var-keyword parameter, the documented type should be the value type, which is bytes/int in this case, not dict.
+1 I think that zope mypy extension can detect this type of errors. |
There was a problem hiding this comment.
Wow. Great work. Thanks!
This can be merged.
Looking forward for updating pydoctor and have it fail on workings
RIght now, there are some warinings in pydoctor but the Documentation run is still green.
https://github.com/twisted/twisted/runs/1464285550#step:8:29
We still have the issue that the processing order of circular dependencies can determine whether a reference is found or not. I'm not sure if that is the cause for this particular failure, but it could cause failures like this, in a flaky way. So while I agree with the goal, I don't think activating "strict mode" is feasible yet with the upcoming pydoctor release. It will require bigger changes, such as separating the code model (implementation side) from the doc model (public API side). |
|
Looking at the error message, it does seem like this is an outdated version of pydoctor being used (we improved the phrasing of that particular message), so perhaps this error will be gone after updating. |
Yep. see https://github.com/twisted/twisted/blob/trunk/tox.ini#L135 |
Contributor Checklist:
tox -e lintto format my patch to meet the Twisted Coding StandardI have updated the automated tests.reviewto the keywords field in Trac, and putting a link to this PR in the comment; it shows up in https://twisted.reviews/ now.Something I noticed while doing this is that
ITransport.writeSequence()usesdataas its argument name, but a lot of implementations use different names such asseqandiovec. I think these should be considered bugs, since these arguments can currently only be passed safely positionally, not via keywords. It will also cause problems once type annotations are added and mypy no longer ignores these methods.