[Twisted-Python] Re: [Twisted-commits] Document the likley consequence of non running of unit tests

[Bruce Mitchener]

Itamar,

Itamar Shtull-Trauring wrote:
> Bruce Mitchener wrote:
> 
>> Because I have patches in my tree that aren't checked in yet that add 
>> that documentation, along with docs for other parts of Woven, but 
>> Donovan and I have been discussing various changes to the widgets and 
>> how things work in that area.
> 
> I rather tend towards your other opinion, that everything should have docs,
> even if it will change. But this does show the problem with requiring 
> docs for everything leading to reverting code - everyone always has a 
> reason why they didn't need to in *this* case. Or they didn't have time 
> or whatever.

I'd meant to suggest that we at least have some sort of policy on 
documentation that is as clearly stated as that for running tests.  I 
don't really care what the policy is, as long as the situation improves 
past the state that Twisted is currently in.

> Merciless taunting should be sufficient in most cases in solving this. 
> Although I'm tending towards outright violence against whoever is 
> responsible for twisted.python.reflect.refrump.

Agreed. And you could argue that Moshez's rudeness encouraged me to 
finally check in a tiny subset of the docs that I have in my tree and 
that's a good thing.

It'd be nice to see some further constructive discussion of this.  We'll 
also need to update the coding standard to reflect the usage of epydoc 
rather than HappyDoc as well.  There are probably other updates that 
could and should be made as well.

For anyone who's missed it, the Epydoc site (http://epydoc.sf.net/) has 
been updated with some docs.  It should be seeing a 1.0 release as well 
fairly soon, so now's a good time to contribute patches for features 
that we'd like to see in corporated.

  - Bruce