id,summary,reporter,owner,description,type,status,priority,milestone,component,resolution,keywords,cc,branch,branch_author,launchpad_bug
3455,CONNECTION_LOST not an Integer...,mforbes,,"Several docstrings, notably those for the writeSomeData() method of t.i.a.FileDescriptor, claim that the return value is an integer reporting the number of bytes sent, or a negative integer reporting that the connection was lost.

The implementations, however, return t.i.main.CONNECTION_LOST which is an exception, not an integer.

Apart from the incorrect docstrings, returning an exception makes it quite difficult to test for errors.  For example:

{{{
bytes_sent = self.connection.writeSomeData(...)
if 0 < bytes_sent:
    Still get here, even if connection is lost.
}}}

One has to check if the return value is explicitly CONNECTION_LOST, or if it is an instance of int etc.

Suggestion: Have writeSomeData throw the exception, or revert back to using an integer...

A quick grep indicates that this would require changes in the following files.

./Twisted/twisted/internet/_javaserialport.py
./Twisted/twisted/internet/_posixserialport.py
./Twisted/twisted/internet/abstract.py
./Twisted/twisted/internet/fdesc.py
./Twisted/twisted/internet/process.py
./Twisted/twisted/internet/tcp.py
./Twisted/twisted/protocols/htb.py
./Twisted/twisted/protocols/pcp.py
./Twisted/twisted/test/test_internet.py
./Twisted/twisted/test/test_pcp.py
",defect,closed,normal,,core,fixed,documentation,thijs,branches/writesomedata-docs-3455,exarkun,